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Preface 





Intended Audience 


This document describes VMS RMS control blocks and services for 
programmers. 





Document Structure 


This document consists of three parts and two appendixes. 


Part I contains general information in four sections: 


— Chapter 1 introduces the reader to VMS RMS functions and 
associated control blocks. 


— Chapter 2 discusses the VMS RMS program interface that applies to 
using any VAX programming language. 


— Chapter 3 describes the program interface with VAX MACRO, 
including how to use VMS RMS macros. This information will also be 
of interest to advanced programmers using other VAX programming 
languages. 


— Chapter 4 describes the groups of VMS RMS services and provides 
VMS RMS example programs using VAX MACRO. 


Part II describes the VMS RMS control blocks and their associated fields, 
in Chapter 5 through Chapter 18. This information is intended for a 
programmer using any VAX programming language. 


Part III describes the VMS RMS services, including the control block fields 
accessed by each service. This information is intended for a programmer 
using any VAX programming language. 


Appendix A lists VMS RMS messages. 


Appendix B contains the formats and associated usage notes for the VMS 
RMS control block initialization and store macros used by VAX MACRO 
programmers. Note that this material was formerly located in Part III. 





Associated Documents 


The following documents contain information related to this reference 
manual: 


The Introduction to VMS System Routines and the VMS System Services 
Volume contain information about the calling routines on a VMS system. 


The Guide to VMS File Applications contains related information about 
VAX RMS, FDL, and the use of files. 


The VMS Networking Manual discusses the support of VMS RMS options 
for remote file access to non-VMS systems. For example, when the 
remote system is a PDP-11 system running RMS-11, Prolog 3 index files 
are not supported and some VMS RMS key definition XAB fields, as well 
as other control block fields, are not fully supported. 
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Preface 


For additional information about remote file access between VMS systems, 
see the VMS I/O User’s Reference Volume. 





Conventions 
Convention Meaning 
In examples, a key name (usually abbreviated) 


shown within a box indicates that you press 

a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 


CTRL/C A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 


box. 
$ SHOW TIME In examples, system output (what the system 
05-JUN-1988 11:55:22 displays) is shown in black. User input (what 


you enter) is shown in red. 


$ TYPE MYFILE.DAT In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 


input-file, ... In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 


{[logical-name] Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 


quotation marks The term quotation marks is used to refer 

apostrophes to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 
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Convention 


lowercase letters and words 


uppercase letters and words 


Preface 


Meaning 


Lowercase letters and words used in format 
statements in this manual represent information 
that you must supply. Such lowercase 
information may contain hyphens for readability. 
The accompanying text defines the information 
to be supplied. For example: 


window-size 
address 


Uppercase letters and words, equal signs (=), 
angle brackets ( <> ), and dollar signs ($) 
must be coded as shown. For example: 


RAT=<BLK , CR> 
$OPEN 


Information enclosed within braces indicates 
that you may choose any one of the enclosed 
values. 

FIX 

STM 

STMCR 
For example: RFM= STMLF : 

UDF 

VAR 

VFC 


Preface 
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Convention 


[] 


Meaning 


Arguments enclosed within square brackets are 

optional, but if an optional argument other than 

a trailing optional argument is omitted, you must 
include a place holder for the omitted argument. 
This rule is shown syntactically below: 


$OPEN INFAB [, [ERR] [,SUC]] 


If you use either or both of the optional 
arguments, you must include the comma shown 
in the outside set of brackets. This comma 
acts as a delimiter between the first and second 
arguments when you use the second argument. 
When you omit the second argument and use 
the third argument, this comma acts as a place 
holder for the omitted argument. If you do not 
use either of the optional arguments, you can 
omit the comma. 


Here is an example of an instance in which the 
first optional argument is used and the second 
is omitted: 

$OPEN INFAB , ERR 
Here is an example of an instance in which the 
second optional argument is used and the first 
is omitted: 

$OPEN INFAB, ,SUC 
Here is an example of an instance in which only 
the required argument is used: 


$OPEN INFAB 





New and Changed Features 


e Enhancements to the DAP/FAL interface 


DAP and FAL are the components of VMS RMS that extend record and 
file access through the network. The new features provide you with 
information about accessing files and records across a network including 
parameters that affect performance, functionality with other VMS systems, 
and functionality with non-VMS systems. 


To implement the enhancements, you open a file with a new XAB called 
the XABITM. You declare a XABITM in the same manner as other XABs 
and you select the appropriate features by means of fields within the 
XABITM structure. 


Most of the network file access controls are implemented explicitly 
through XABITM in conjunction with either the $CREATE service or the 
$OPEN service. Informational functions are implemented explicitly with 
the $DISPLAY service and implicitly with $CREATE and $OPEN. 


e¢ Performance monitoring enhancements 


You can also use the XABITM to gather RMS performance statistics by 
way of the Monitor Utility. To gather statistics for an RMS file, you must 
create the file with a XABITM that enables statistics by way of the related 
item list. You can also enable statistics gathering from either the FDL 

or the DCL interface. If statistics gathering is enabled, it can only be 
disabled from DCL. 


e Enhancements to RMS multinational keys 


The enhancements to the RMS multinational key functions provide a way 
to use alternative (non-ASCII) collating sequences. The multinational 
key enhancements are based on the National Character Set Utility that 
permits you to define alternative collating sequences for special characters 
and to establish and maintain libraries of collating sequences. This 
eliminates having to redefine an alternative collating sequence when the 
application requires it. For information on NCS, see the VMS National 
Character Set Utility Manual. 


The use of multinational keys requires the setting up of user-specified 
collating sequences for multinational characters on a per-key basis. With 
these collating keys, a record field can be sorted according to several 
languages where each language has its own key of reference. 


e Enhanced Asynchronous Interface 


The FAB$V_ASY option has been added to the VMS RMS asynchronous 
interface to support file operations. File operations and record operations 
can request notification of the synchronous completion of asynchronous 
operations with the FAB$V_SYNCSTS option or the RAB$V_SYNCSTS 
option, respectively. 
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General Information About VMS Record 
Management Services 


Part | introduces the reader to general mechanisms and conventions 
associated with VMS Record Management Services (VMS RMS). It 
discusses the following topics: 


Argument passing 

Control blocks 

Symbols defined by VMS RMS 

Invoking VMS RMS services 

VMS RMS macros used by VAX MACRO programs 
Syntax conventions for VAX MACRO 

Example programs in VAX MACRO 


1 _—_ Introduction to VMS RMS 


This section presents an overview of the general functions available through 
VMS Record Management Services (VMS RMS). It also briefly describes the 
VMS RMS services and control blocks. Unless otherwise stated, the term 
RMS refers to VMS RMS. 





1.1 VMS RMS Functions 


VMS RMS is a set of generalized services that assist application programs in 
processing and managing files and their contents. VAX MACRO programs 
can invoke these services by using the corresponding macros supplied in 
the system library SYS$LIBRARY:STARLET.MLB. (VMS RMS automatically 
searches this library for unresolved references when you assemble a source 
program.) Other VAX languages may support a similar means of invoking 
VMS RMS services. 


Although VMS RMS supports unit-record devices, such as terminals and 
printers, it primarily provides a comprehensive software interface to mass 
storage devices, such as disk and magnetic tape drives. 


VMS RMS provides a variety of disk file organizations, record formats, and 
record access modes from which you can select the processing techniques 
best suited to your application. VMS RMS supports sequential, relative, and 
indexed file organizations, and fixed-length and variable-length record formats 
are supported for each file organization. (Relative and sequential files also 
support other record formats.) The VMS RMS record access modes permit 
you to access records within these files sequentially, directly by key value, 
directly by relative record number, or directly by record file address (RFA). 
VMS RMS also provides a means of performing block I/O operations to 
support users with certain performance-critical applications (such applications 
may require user-defined file organizations and/or record formats). 


VMS RMS ensures safe and efficient file sharing by providing 


¢ Multiple file access modes, to allow file sharing to be consistent with the 
file operations 


e Automatic record locking in applicable file access modes, to ensure data 
integrity during record updates 


¢ Optional buffer sharing by multiple processes accessing the same file, to 
minimize I/O operations 


VMS RMS also enforces the security requirements of a multiuser system with 
potential multinode access by restricting file access to one or more user UIC 
types and to a list of user names. 


For systems that support DECnet network capabilities, VMS RMS provides 
a subset of file and record management services through the Data Access 
Protocol (DAP) to remote network nodes. Network DAP remote file 
operations are generally transparent to application programs. 
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1.2 Passing Arguments to VMS RMS 


The flexibility inherent in VMS RMS would require application programs to 
pass a multitude of arguments to perform such common operations as file 
creation and access. To eliminate the potential problems associated with 
passing numerous arguments for each service call, the application program 
places the arguments in one or more data control blocks before it invokes any 
VMS RMS service. The only argument required to invoke most VMS RMS 
services is the symbolic address of the appropriate data control block. 


1.2.1 VMS RMS Services and Control Blocks 


Because VMS RMS operates on files and records, its services generally fall 
into one of two groups: 


e File services that create and access a new file, access (open) an existing 
file, extend the disk space allocated to a file, close a file, obtain file 
characteristics, and perform other functions related to files 


e Record services that get, find (locate), put (insert), update, and delete 
records, and perform other operations not directly related to record I/O, 
such as associating one or more record streams (methods of accessing 
records) with an open file 


To support service operations, VMS RMS provides two types of control 
blocks: 


¢ Control blocks that provide file-related arguments to VMS RMS file 
services 


¢ Control blocks that provide record-related arguments to VMS RMS record 
services 


1.2.2 Control Blocks for File Services 


File services use a control block called the file access block (FAB). When 
creating a file, the user must store arguments in the FAB that define the 
file characteristics, the file specification, and certain run-time access options. 
When your process opens an existing file, the FAB specifies only the file 
specification and the run-time access options. 


There are three categories of FAB arguments and the following list briefly 
introduces each: 


¢ File specification arguments identify primary and default file 
specifications used at run-time to locate the file. 


e File characteristics arguments specify the file organization, record type, 
allocation information, and other information. 


e Run-time access options specify the operations that can be done by 
the initiating process and the operations that can be done by sharing 
processes, a variety of file-processing options, and the address (or 
addresses) of one or more control blocks whose fields supplement or 
supersede the information in the FAB. 
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The two types of optional control blocks that can supplement or supersede 
the information in the FAB are the name block (NAM) and the extended 
attribute block (XAB). 


The NAM block supplements the file specification information available in 
a FAB. It is especially useful for locating and opening files when the file 
specification is entered by an interactive user or when a file specification 
includes a wildcard character or a search list logical name representing 
multiple files. 


There is only one type of NAM block, and you usually associate only one 
NAM block with a file. To provide an extra level of defaults for a file 
specification, however, VMS RMS will apply defaults using additional NAM 
blocks that contain the file specifications of related files. 


A XAB usually supersedes and supplements the file characteristics specified 
in the associated FAB and multiple XABs may be used to support a single 
file. There are several types of XABs, each of which is used for a different 
purpose. Each type of XAB has a 6-letter mnemonic name consisting of 
the prefix “XAB” followed by a 3-letter mnemonic that relates to the XAB 
function. For instance, the XAB that supplements and supersedes the file 
allocation information in the FAB is called an allocation control XAB, or 
XABALL. 


The XABs used for file operations are briefly described in the following list: 


¢ Allocation control XAB (XABALL)—allows greater control over disk file 
allocation and positioning during file allocation. 


e Date and time XAB (XABDAT)—specifies date and time values for backup, 
creation, expiration, and revision times, and the revision number. 


e File header characteristic XAB (XABFHC)—receives the file characteristics 
information contained in the file header block. 


e Item list XAB (XABITM)—provides a convenient means for using item 
lists to pass information between RMS and the application program. 


e¢ Journaling XAB (XABJNL)—supports file journaling operations. 


e  =Key definition XAB (XABKEY)—defines the key characteristics to be 
associated with an indexed file. 


e File protection XAB (XABPRO)—defines file protection characteristics 
that specify what class of users or list of users can have certain specified 
access rights. For ANSI magnetic tape files using HDR1 labels, this XAB 
specifies the accessibility field character. 


e Revision date and time XAB (XABRDT)—specifies the revision date and 
time value and the revision number associated with a file. 


e Recovery unit XAB (XABRU)—supports the use of recovery units to 
assure data file integrity. 


¢ Summary XAB (XABSUM)—stores additional file characteristics associated 
with an indexed file. 
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1.2.3 Control Blocks for Record Services 


Record services use a control block known as the record access block, or RAB. 
Some of the arguments the user must store in the RAB include the address of 
the related FAB, the address of input and output record buffers, the type and 
size of general I/O buffers, whether a file’s records will be accessed directly 
or sequentially, certain tuning options, and other information. 


An extended attribute block (XAB) can both supersede and supplement the 
record characteristics specified in the RAB. As with a XAB that supersedes 
and supplements a FAB, a XAB that supersedes and supplements a RAB has 
a 6-letter mnemonic name consisting of the prefix “XAB” followed by three 
letters. Note that there are only two XAB types for record operations, the 
terminal XAB (XABTRM) and the recovery unit XAB (XABRU). 


The XABTRM defines the symbolic address and length of a user-supplied 
argument list that defines the terminal operation and provides more flexibility 
than using RAB fields. 


See the VAX RMS Journaling Manual for details relating to the use of the 
XABRU. 


1.2.4 The Dual Purpose of Control Blocks 


Control blocks provide input to VMS RMS services and they provide output 
from VMS RMS services including the following run-time information: 


¢ Detailed file characteristics, including file organization, record format, and 
record size 


¢ Device characteristics 
e File, directory, and device identifiers 
e The address (location) and length of a requested record 


e Returned condition values 


For this reason, certain programs specifically allocate a NAM block or one 
or more XABs dedicated to receiving information returned by VMS RMS 
services. Typically, such information can be examined to determine how the 
file should be processed. 


In most cases, however, control blocks are used both to transmit and to 
receive information between the application program and VMS RMS and 
should not be located in a read-only program section. 


Be sure that control block fields not currently used by a particular service 
have valid default values because future versions of VMS RMS may use 
them. This applies also to control block fields that are currently described 
as “ignored for DECnet operations” because future versions of VMS RMS or 
DECnet may support those fields. 


2 =‘ TheProgram Interface with VMS RMS 


This section introduces the application program interface with VMS RMS that 
is applicable to all VAX languages in terms of the following: 


¢ The VMS RMS run-time processing environment 
¢ VMS RMS symbol-naming conventions 

e The calling sequence for VMS RMS services 

e Allowable program execution modes 


¢ Condition values returned by VMS RMS services 





2.1 The Run-Time Environment and VMS RMS Programming 


The VMS RMS run-time processing environment consists of a set of blocks 

and the run-time services. The control block fields accessed by each service 
specify to VMS RMS the appropriate file and record operations. Depending 
on the operation, VMS RMS uses one or more control blocks by referring to 
one or more fields as input to, or output from, the operation. 


To use VMS RMS, you must do the following: 


1 Allocate the appropriate control block, usually at assembly time or 
compilation time. Control blocks must not reside in read-only storage 
and should be aligned on a longword boundary to maximize efficiency. 


2 Insert the appropriate values into the control block fields before you 
invoke the related service. 


3 Invoke the appropriate VMS RMS service. As part of this step, a 
condition value should always be examined. 


To perform advanced VMS RMS functions, you may need to set various 
control block field values at run time between the time the file is opened and 
when the VMS RMS service is invoked. 


Note that VAX languages perform some of these steps transparently when a 
particular language statement or macro is present in a source program. 


Two fields in each control block, the block length (BLN) field and the block 
identifier (BID) (or block code (COD) field in a XAB), define the length of 
the control block (in bytes) and identify the control block type, respectively. 
These internal VMS RMS fields are always used as input arguments by the 
VMS RMS service that accesses the control block and must be set before 
the control block can be used. The fields are initialized automatically by 
the appropriate VAX MACRO assembly-time initialization macro and must 
contain the correct value for the type of control block. After the block length 
and block identifier fields are established, you must treat them as read-only 
fields until the control block is no longer needed. 


Part II describes each control block field in detail, including its length and its 
symbolic name. 
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Appendix B lists the VAX MACRO calling format for each VAX MACRO 
control block macro. 


Part III lists the calling format for each service together with the input control 
block fields and the output control block fields for each service. 





Conventions for Naming Fields 


VMS RMS uses mnemonic names to identify control block fields. For 
example, the mnemonic name for the FAB allocation quantity field is ALQ. 


The mnemonic name (usually consisting of three characters) serves as a suffix 
to a symbolic name that identifies the location of each control block field. 
You should use the symbolic names to be sure you place values in the correct 
control block fields. VMS RMS defines each symbolic name as a constant 
value equal to the offset, in bytes, from the beginning of the control block to 
the beginning of the field. These field names are thus called symbolic offsets. 


Symbolic offset names are defined when the appropriate VAX MACRO control 
block initialization macro is used, when the appropriate VAX MACRO control 
block symbol definition macro is used, and when some VAX languages invoke 
VMS RMS. Alternatively, all control block symbolic offset names are available 
when you use the VAX MACRO $RMSDEF macro in a VAX MACRO program 
or procedure. 


The format of the symbolic offsets consists of a 3-letter control block identifier 
(FAB, NAM, XAB, or RAB), a dollar sign ($), a 1-letter indicator of the length 
of the field (B, W, L, Q, or T), an underscore (_), and the field mnemonic, 
which is usually three letters. 


The general format of the symbolic offset is shown in the following example: 
ccc$x_fff 


The components of the symbolic offset format are summarized in the 
following table. 
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Component _ Length Description 

ccc 3 letters Identifies the type of control block: 
FAB, NAM, XAB (for all XABs), or 
RAB. 

$ 1 character Separates the control block 


identifier from the field length 
identifier; a dollar sign ($). 


X 1 letter Identifies the length of the field: 
B for byte, W for word, L for 
longword, QO for quadword, T for 
text buffer address. Symbolic 
length fields are identified by 
the letter S in this position. For 
example, the value field XAB$S_ 
CACHE_TMO specifies the number 
of bytes allocated for defining the 
value of the cache timeout. See 
text for exceptions. 


_ 1 character Separates the field length identifier 
from the field name; always an 
underscore {_.). 

fff 3 or more letters Identifies the mnemonic name 


of the field, which is used in the 
VAX MACRO control block macro. 
Some mnemonics contain more 
than three letters; for example, 
symbolic offset XAB$B_PROLOG 
(from XABKEY). 


For example, the FAB field whose mnemonic is ALQ has a length of one 
longword and is identified by the symbolic offset FAB$L_ALQ. The field 
NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its 
name, the related file field. 


Exceptions to the length designation are NAM$W_DID, NAM$W_FID, 
XAB$W_RFI, and RABSW_RFA. These symbolic offsets mark the locations of 
fields that are three words, not one word. 


The length of a T field is specified by the corresponding S field; for example, 
the length of the NAM$T_DVI field is specified by the symbolic value field 
named NAM$S_DVI. 


When a control block field contains options identified by bits, each valid bit 
location has a symbolic offset name. Certain control block fields are binary 
options fields consisting of bit values. For these bits in a binary options field, 
the format of symbolic names resembles the format of the field names, except 
for the length indicator. Instead of identifying the field length, which is 
always one bit, the length field indicates whether a mask value (M) or bit 
offset (V) is defined by the symbolic name, as described below. 
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2.2 Conventions for Naming Fields 


Format Description 

xxx$M _fff Indicates a mask value in a binary options field, typically where 
multiple bit options can be chosen. Used to set or clear bit 
values. 

xxx$ V_fff Indicates the symbolic bit offset (number of bits from the 


beginning of the binary options field). Used to test bit values or 
to set bit values. 


The xxx identifies the control block (FAB, NAM, XAB, or RAB); the $ and — 
are separator characters, and the fff defines the mnemonic for the bit option. 
For example, the option CTG in the FAB file-processing options (FOP) field 
has a symbolic bit offset of FAB$V_CTG and a mask value of FABSM_CTG. 


Another type of field can contain only certain values; thus there are no mask 
values or symbolic bit offsets. Unlike a binary options field, each possible 
value is identified by a symbolic constant value, in the following form: 


xxx$C_fff 


Note that the letter C replaces the letter M, denoting that this field is a 
constant (keyword) value field, not a mask value field. For example, the 
file organization (ORG) field of the FAB (FAB$B_ORG) can only contain 
the values FAB$C_IDX (indexed), FAB$C_REL (relative), or FAB$C_SEQ 
(sequential). In some instances, the letter K is used to denote a constant 
(keyword) value field in place of the letter C; otherwise, the naming 
convention is the same. 


When specifying control block field locations, avoid using actual byte 
displacement values to identify control block field locations; instead, use the 
supplied symbolic offsets. VMS RMS control block field locations may not 
always be the same from release to release of VMS; however, the symbolic 
offset names that identify the field locations always identify the same fields. 





2.3 The VMS RMS Calling Sequence 


VMS RMS uses the standard VAX calling sequence and conventions, and 
preserves all general registers across a call, except for register 0 (RO) and 
register 1 (R1). When the service completes execution, it returns control to 
the calling program, passing a condition value in RO. You should analyze the 
completion value to determine the success or failure of the service and to alter 
the flow of execution of your program, if necessary. Where applicable, you 
should use the STS field and the STV field of the appropriate control block 
for signaling errors, instead of RO. For additional information about VMS 
RMS completion values, see Section 2.4. 


When calling a VMS RMS service, you must provide an argument list to 
specify the associated control block (FAB or RAB) and, optionally, any 
completion routines. The argument list is from two to four longwords in 
length, as shown in Figure 2-1. (The Rename service, however, uses a 
5-longword argument list.) 
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Condition Values 
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Figure 2-1 Argument List Format 


31 8 7 0 


contro! block address 


| l 
I error completion routine address ! 
I | 






ott otc c ct cc ct ec oe er nr ee ee ee ee ee ee | 2 Optional 


ZK-875-82 


VMS RMS interprets the fields in the argument list as follows: 


¢ The argument count field contains a binary value, from 1 through 3, 
representing the number of arguments in the argument list. For the 
Rename service only, set this value to 4. 


¢ The control block address field contains the address of either the FAB (for 
file operations) or the RAB (for record operations). 


e The error completion routine address field optionally contains the address 
of the entry mask of a user-written completion routine to be called if the 
requested operation fails. If used, the completion routine executes as an 
asynchronous system trap (AST). 


e The success completion routine address field optionally contains the 
address of the entry mask of a user-written completion routine to be 
called if the requested operation completes successfully. If used, the 
completion routine executes as an asynchronous system trap (AST). 


¢ The new FAB address field (not shown in Figure 2-1) contains the address 
of the FAB that contains the new file name for the Rename service. This 
field must be present only for the Rename service. 





Before returning to your program from a file or record operation, VMS RMS 
indicates the success or failure of the operation by setting a condition value in 
the completion status code field (STS) of the associated control block (FAB or 
RAB). 


When first returning to your program after a call to an operation, VMS 
RMS also sets general register 0 to the value in the status code field. In 
asynchronous operations, register 0 may simply indicate that the operation 
has been initiated. 


In general, you may receive one of many error or success codes from an 
operation. (The discussion of each VMS RMS service in Part III includes a 
list of the possible condition values that you can receive.) (See Appendix A 
for a complete list of all VMS RMS status codes.) You should test for success 
by checking only the low-order bit of the status code for a true condition (bit 
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set). The three low-order bits returned in the status code indicate the severity 
of the code. The severity codes are as follows: 


001 (1) Success (low-order bit set). 
011 (3) Information (low-order bit set). 
000 (0) Warning; indicates a nonstandard condition. The operation may 


have performed some, but not all, of the requested function. 


010 (2) Error; you must recognize that a problem exists and provide a 
contingency plan in your program for such a condition. 


100 (4) Severe error; normally caused by program logic errors or other 
unrecoverable conditions. 


The usual method of testing the completion status is to examine register 0 for 
success, failure, or specific completion values. For certain completion values, 
VMS RMS returns additional information in the status value field (STV) of 
the control block. The description of the codes in Appendix A indicates the 
instances when the STV contains such information. 


The STS and STV fields should be used to signal VMS RMS errors to 
ensure that the error message includes all relevant information. For the 

file processing and file naming services, use the STS and STV fields of 

the specified FAB (use the old FAB for the Rename service). For record 
processing and block I/O processing services, use the STS and STV fields of 
the corresponding RAB. (Consult Table 3-2 if you are not sure of the group 
to which a particular VMS RMS service belongs.) 


The recommended way to signal VMS RMS errors is to provide both the STS 
and STV fields of the RAB or FAB as arguments to the Run-Time Library 
(RTL) routine LIB$SIGNAL (or LIB$STOP). Certain VAX languages provide 

a built-in means of signaling errors, such as by providing a system-defined 
function. For a more detailed explanation of condition signaling and invoking 
RTL routines, see the VMS Run-Time Library Routines Volume. 


VMS RMS services are considered system services for the purpose of 
generating system service exceptions on errors. You can choose whether 

to test and handle errors in your program or set the system service failure 
exception mode (using the Set System Failure Exception Mode system service, 
SYS$SETSFM) to have failures automatically signaled. For most applications, 
especially if a high-level language is used, testing and handling errors in 
your program is the preferred method. If you test for error conditions in 
your program, you should be sure to disable any unwanted system service 
exception generation. 


Note that if the FAB or RAB is invalid or inaccessible, then the error 
completion routine will not attempt to store the error code in the STS 
field of an invalid control block structure. The following errors can be 
detected only by testing RO (or by enabling system service failure exception 
mode), following the completion of a VMS RMS operation (even if an error 
completion AST has been specified): 
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RMS$_BLN Invalid block length field (either FAB or RAB) 
RMS$_BUSY User structure (FAB/RAB) still in use 

RMS$_FAB FAB not writable or invalid block ID field 

RMS$_RAB RAB not writable or invalid block !D field 

RMS$_STR User structure (FAB/RAB) became invalid during operation 


These completion codes indicate that the FAB or RAB is invalid or 
inaccessible. These completion codes can only be detected and signaled 
using RO, but are usually rare and, if they occur at all, would most likely 
occur during initial program debugging and testing. Thus, you must examine 
the completion value in RO (instead of the STS field of the FAB or RAB) for 
the completion codes listed above. If necessary, your program could test for 
these errors and, if encountered, signal these completion values using RO 
instead of the STS and STV fields. 





2.5 Allowable Program Execution Modes 


Generally, VMS RMS executes in either executive mode or executive AST 
mode. When a VMS RMS operation is initiated, processing begins in 
executive mode. If device I/O is necessary to process the request, the $QIO 
system service is called. VMS RMS specifies an executive-mode AST to 
signal completion. At this point, VMS RMS exits from executive mode. If the 
operation is being performed asynchronously, control is returned to the caller; 
if the operation is synchronous, VMS RMS waits for an event flag in the 
access mode of the caller. When the I/O is complete, VMS RMS continues 
processing in executive AST mode. Thus, user-mode ASTs can be serviced 
while a synchronous VMS RMS operation called from user mode is awaiting 
I/O completion. However, processing in user mode during an asynchronous 
VMS RMS operation is interrupted by VMS RMS processing in executive AST 
mode when I/O completes. 


VMS RMS should not be called from kernel mode, from executive AST mode, 
nor from executive mode when executive-mode ASTs are disabled. 


2.6 Reserved Event Flags 


VMS RMS uses system-reserved event flags to synchronize its internal 
operations. VMS RMS reserves event flags 27, 28, 29, and 30 for possible 
use; in addition, event flag 31 is used to specify a “do not care” event flag for 
asynchronous processing. 


2.7 DEC Multinational Character Set 


You can use any character in the DEC Multinational Character Set in VMS 
RMS records, including the key value of an indexed file. Keys are collated 
according to their corresponding character code value. 


For a list of characters in the DEC Multinational Character Set, see the VAX 
EDT Reference Manual. 


‘3. VMSRMS Macros and VAX MACRO Programming 


This chapter describes the four types of VMS RMS macros used in VAX 
MACRO programming. It begins with a description of each of the four types 
of macros, macro naming conventions and macro syntax rules. The remainder 
of the chapter describes how to use the macros and includes examples for 
each of the four types. Note that in the remainder of Part I, the use of 

the term “macro” refers to a program macro written in the VAX MACRO 
language. 





3.1 VMS RMS Macros 


VMS RMS provides four types of macros used by VAX MACRO programs 
implementing VMS RMS features. The functions these macros provide are 
described below. 


Control block initialization macros initialize a control block at assembly 
time. This type of macro performs five separate actions: 


— Allocates space within the program image for the specified control 
block 


— Defines the symbolic names associated with a control block 
— Initializes certain control block fields with internally used values 
— Initializes specified control block fields with user-specified values 


— Initializes certain fields with system-supplied defaults (does not apply 
to all control block macros) 


As an alternative to using this type of macro, an application program 
would have to allocate each control block needed with its correct 
length, initialize the internally used fields with the correct values, 
and initialize or set user-specified values in the appropriate fields.’ It 
is peseegh recommended that the supplied macros be used for VAX 
MACRO programs. 


Control block symbol definition macros define control block symbolic 
names at assembly time without allocating and initializing the control 
block. These macros are needed only when the corresponding 
initialization macro is not used and the symbols are not defined by 
the VAX language used. 


Control block store macros set (or reset) specified fields in a control block 
with user-specified values at run time. Alternatively, you can set values 
in control block fields at run time using VAX MACRO instructions, such 
as the MOVx and MOVAx instructions. Field locations are made available 
using the symbolic name assigned to each control block field to represent 
its offset from the start of the control block. 
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e Service macros invoke VMS RMS services at run time. When a service 
is invoked, one or more control blocks are examined for required field 
values. Values are also returned in one or more control blocks, including 
condition codes. VMS RMS services conform to the VAX calling standard 
and thus can be invoked directly from any VAX language, if needed, 
without the calling program having to use the supplied macro. However, 
the appropriate control block must be present with the appropriate field 
values set for the requested operation. 


VMS RMS stores its macros for use by VAX MACRO programs in 
SYS$LIBRARY:STARLET.MLB. 


3.1.1 Conventions for Naming VMS RMS Macros 
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The corresponding macro name that initializes each control block at assembly 
time consists of a dollar sign ($) followed by the name of the control block. 
Thus, the macro that initializes a FAB is called $FAB; the macro that initializes 
an XABALL is called $XABALL. 


The macros that define symbolic offsets without performing control 
block initialization contain the suffix “DEF” following the corresponding 
initialization macro name; for example, $FABDEF and $XABALLDEF. 


For the macros that set control block field values at run time, the name of the 
assembly time macro is followed by _STORE. Thus, the $FAB macro has a 
$FAB_STORE macro for setting FAB values at run time and the $XABALL 
macro has a $XABALL_STORE macro for setting XABALL values at run time. 


Table 3-1 summarizes the control blocks, their assembly time macro names, 
and their functions. 


Table 3—1 User Control Blocks 


Control Macro 
Block Names Function 
FAB Describes a file and contains file-related 
information 
$FAB Allocates storage for a FAB and initializes 
certain FAB fields; also defines symbolic offsets 
for a FAB 
$FABDEF Defines symbolic offsets for a FAB 
$FAB_STORE Moves specified values into a previously 
allocated and initialized FAB 
NAM Contains file specification information beyond 
that in the file access block 
$NAM Allocates storage for a NAM and initializes 


certain NAM fields; also defines symbolic 
offsets for a NAM 


$SNAMDEF Defines symbolic offsets for a NAM 


$NAM_STORE Moves specified values into a previously 
specified and allocated NAM 
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Table 3-1 (Cont.) User Control Blocks 


Control Macro 
Block Names Function 
RAB Describes a record stream and contains record- 
related information 
$RAB Allocates storage for a RAB and initializes 
certain RAB fields; also defines symbolic offsets 
for a RAB 
$RABDEF Defines symbolic offsets for a RAB 
$RAB_STORE Moves specified values into a previously 
specified and allocated RAB 
XAB Contains file attribute information beyond that 
in the file access block; for XABTRM, contains 
information beyond that in the record access 
block 
$XABxxx' Allocates and initializes an XAB 
$X ABxxxDEF Defines symbolic offsets for an XABxxx 


$XABxxx_STORE Moves specified values into a previously 
specified and allocated XABxxx 


'The variable xxx represents a 3-character mnemonic. 


VMS RMS services can be called from any VAX language using the VAX 
Procedure and Condition Handling standard. VMS RMS services are system 
services identified by the entry point prefix “SYS$” followed by three or 
more characters. In the corresponding VAX MACRO macro name, the “SYS” 
prefix is not used. For example, the Create service has an entry point of 
SYS$CREATE and a VAX MACRO macro name of $CREATE. A complete 
description of each service is provided in Part III. 


Table 3-2 describes the functions of each VMS RMS service, including the 
service entry point name and its corresponding VAX MACRO macro name. 


Table 3-2 VMS RMS Services 
Service Name Macro Name Description 
File Processing and File Naming Macros 


SYS$CLOSE $CLOSE Terminates file processing and disconnects 


all record streams 

SYS$CREATE $CREATE Creates and opens a new file of any 
organization 

SYS$DISPLAY $DISPLAY Returns the attributes of an open file to the 
application program 

SYSSENTER' SENTER Enters a file name into a directory 

SYSS$ERASE $SERASE Deletes a file and removes its directory 
entry 


'This service is not supported for DECnet operations involving remote file access between 
two VMS systems. 
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Table 3—2 (Cont.) VMS RMS Services 


Service Name 


Macro Name 


Description 


File Processing and File Naming Macros 


SYSSEXTEND 
SYSSOPEN 


SYS$PARSE 
SYS$REMOVE' 
SYS$SRENAME 
SYS$SEARCH 


$EXTEND 
SOPEN 


$PARSE 

$REMOVE 
$SRENAME 
$SEARCH 


Record Processing Macros 


SYS$CONNECT 


SYS$DELETE 


$CONNECT 


$DELETE 


SYSS$DISCONNECT $DISCONNECT 


SYS$FIND 
SYS$FLUSH 
SYS$FREE 
SYS$GET 
SYS$NXTVOL' 
SYS$PUT 
SYS$RELEASE 


SYS$REWIND 


SYSSTRUNCATE 


SYSSUPDATE 


SYSSWAIT 


$FIND 
$FLUSH 
$FREE 
$GET 
$SNXTVOL 
$PUT 


$RELEASE 


$REWIND 
$TRUNCATE 
$SUPDATE 


SWAIT 


Extends the allocated space of a file 


Opens an existing file and initiates file 
processing 


Parses a file specification 
Removes a file name from a directory 
Assigns a new name to (renames) a file 


Searches a directory, or possibly multiple 
directories, for a file name 


Establishes a record stream by associating 
a RAB with an open file 


Deletes a record from a relative or indexed 
file 

Terminates a record stream by 
disconnecting a RAB from an open file 


Locates and positions to a record and 
returns its RFA 


Writes (flushes) modified |/O buffers and 
file attributes 


Unlocks all records previously locked by the 
record stream 


Retrieves a record from a file 


Causes processing of a magnetic tape file 
to continue to the next volume of a volume 
set 


Writes a new record to a file 


Unlocks a record pointed to by the contents 
of the RAB$W_RFA field 


Positions to the first record of a file 
Truncates a sequential file 


Rewrites (updates) an existing record in a 
file 


Awaits the completion of an asynchronous 
record operation 


'This service is not supported for DECnet operations involving remote file access between 


two VMS systems. 
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Table 3-2 (Cont.}) VMS RMS Services 


Service Name Macro Name Description 


Block I/O Processing Macros 


SYS$READ $READ Retrieves a specified number of bytes from 
a file, beginning on block boundaries 

SYS$SPACE $SPACE Positions forward or backward in a file to a 
block boundary 

SYSSWRITE SWRITE Writes a specified number of bytes to a file, 


beginning on block boundaries 


3.1.2 Applicable VAX MACRO Syntax Rules 


One of the conventions of VMS RMS control block macros is to use the 
mnemonic name associated with each field as a keyword to identify each 
argument. Using a keyword ensures the accuracy of argument value 
placement regardless of the ordering you use when you code the related 
argument. For example, the mnemonic keyword for the FAB field that 
specifies the allocation quantity is ALQ. Thus, when using the $FAB macro 
to initialize the allocation quantity field, you might use the following macro 
expression: 


INFAB: $FAB ALQ=500 


This macro statement defines the start of the FAB at label (symbolic address) 
INFAB and initializes the allocation field (at symbolic offset ALQ) to provide 
500 blocks of space to the file being created. 


In this instance, if you want to change the allocation value to 250 blocks at 
run time, you could use the following macro expression: 


MOVL #250, INFAB+FAB$L_ALQ , Set allocation quantity 


In fields that contain binary options or keyword values, you should use the 
appropriate keyword or symbolic binary option value. For example, the FAB 
has a field at symbolic offset ORG that specifies the file organization. Three . 
keywords are defined for this field; SEQ (sequential file), REL (relative file) 
and IDX (indexed file). To specify an indexed file organization, you should 
use the following macro expression: 


OUTFAB: $FAB ORG=IDX 


To set this value at run time, you must move the formal title of the value into 
the formal title of the field: 


MOVAL OUTFAB, R5 ; Move address into R5 
MOVB #FAB$C_IDX, FAB$B_ORG(R5) ; Store constant value 


In control block macros, arguments for bit fields that can contain multiple 
values are usually enclosed within left angle ( <) and right angle (> ) 
brackets. Consider the file access (FAC) field (FAB$B_FAC) in the FAB, a bit 
field that can contain multiple values. To permit a process to do get and put 
operations, the following macro expression could be used: 


INFAB: $FAB FAC=<GET,PUT> ; Specify Put and Get operations 
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Control block macro arguments that are interpreted as ASCII characters (such 
as a file specification) are enclosed within left angle ( <) and right angle (> ) 
brackets. The use of the left angle ( <) and right angle (> ) delimiters is 
noted in the format and argument descriptions of the control block macros in 
Part II. 


At run time, you could use the following code sequence to make the file 
accessible to a Get operation: 


MOVAL OUTFAB, R6 ; Move addr into R6 
BBS #FAB$V_GET, FAB$B_FAC(R6), OK ; Branch if set 
BISB #FAB$M_GET, FAB$B_FAC(R6) ; Set if not set 

OK: ; Complete operation 


When you use VMS RMS macros, follow the coding rules used by the VAX 
MACRO assembler as described in the following list: 


e Comments must be separated from the rest of the code line by a 
semicolon (;). For example: 


$FAB BKS=4 ; Bucket size 


e All the arguments for a macro must be coded in a single statement. If the 
arguments do not fit on a line or if you want to use multiple lines, type 
the continuation character, a hyphen (-), as the last character on the line, 
and then continue typing arguments on the next line. Comments can 
follow the hyphen. For example: 


$FAB FNA=FLNAM, - ; Filename address 
ALQ=100, - ; Allocation quantity 
BKS=4 ; Bucket size 


e Arguments and subarguments can be separated from each other by one 
of the following: 


— Acomma, with or without spaces or tabs 
FNA=FLNAM , ALQ=100 

— Aspace 
FNA=FLNAM ALQ=100 

— Multiple spaces or tabs 
FNA=FLNAM ALQ=100 


The comma without a space or tab is preferred. All coding examples in 
this manual use a comma to separate arguments. 





3.2 Using the VMS RMS Macros 


This section provides examples of using the four types of VMS RMS macros. 
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3.2.1 Control Block Initialization Macros 


A major advantage to using the control block initialization macros is that 
they direct the initialization values to the correct field locations in the control 
block. Returned status values do not apply here because RMS evaluates this 
type of macro at assembly time. 


The program location of a control block initialization macro defines the 
beginning of the control block. Because the address of the control block is a 
required argument for most services and for some control block macros, the 
macro name should be preceded by a label, as shown in the following code 
example: 


MYFAB: $FAB 


Arguments usually require an address, such as a symbolic address, or a value. 
VMS RMS initializes the appropriate field by simply taking the supplied 
argument and placing it after the appropriate macro data declaration directive, 
as shown in the following code example: 


.ADDRESS address 
.BYTE value 


There are fields that must be treated as ASCII character strings or they 
become values in a binary options field. Such fields must be enclosed within 
left angle ( <) and right angle (> ) brackets, under the following conditions: 


e When the argument is a file specification (ASCII character string) 


e When more than one argument is supplied for a binary options field, 
where each bit option is identified by a 3-letter mnemonic 


e¢ Where otherwise indicated in the format of the macro, such as for 
UICs and file identifiers in which multiple values separated by commas 
constitute the argument 


Here are several examples: 


MYFAB: $FAB FAC=<GET, PUT>, - ; Multioption field 
FNM=<DEGREE_DAY.DAT>,- ; File specification 
NXT=MYXPRO, - ; XAB address 
ORG=SEQ ; Single-option field 
MYXPRO: $XABPRO PRO=<RWED,RWED,R,R>,- ; File protection 
UIC=<377 , 377> ; UIC 


The complete format of each control block initialization macro is provided in 
Appendix B, showing those arguments that must be enclosed within left angle 
( <) and right angle (> ) brackets. 


Do not position the macro name in a read-only program section, because 
control block fields may receive values during the execution of a service. For 
efficiency, align the control blocks on a longword boundary. The initialization 
macros display an informational message in the listing file if the control block 
is not longword aligned. 


In summary, initialization macros must be placed in a writable data program 
section in which the data has been aligned on a longword boundary. 


3.2.2 


3.2.3 
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Control Block Symbol Definition Macros 
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A control block symbol definition macro includes the macro name only and 
has no arguments. The macro name has the suffix “DEF” following the name 
of the initialization macro that defines all symbols in the affected control 
block. 


Control block symbol definition macros can be placed in any program section. 
VMS RMS does not provide return values for these macros. 


Control Block Store Macros 


A control block store macro consists of executable run-time code, so it must 
be placed within an executable code program section. RO cannot be used to 
return condition codes because these macros may use it to move arguments. 
The only detectable errors are assembly-time errors. 


The calling format of each control block store macro resembles the calling 
format of the corresponding initialization macro except that a control block 
store macro can take a run-time value as an argument. Run-time values 
include date and time values, file identifier values, device identifier values, 
directory identifier values, and record file address values. 


The following list describes other differences between the format of a control 
block store macro and its corresponding control block initialization macro: 


e The argument for the address of the FAB, NAM block, RAB, or XAB to 
receive the argument values is required. This argument can be omitted 
if the control block address is contained in RO. If this argument is not 
a register value in the form Rn, the control block address is loaded into 
RO. This argument is not present in the corresponding control block 
initialization macro. 


e For each argument that requires an address, the store macro uses the 
VAX MACRO instruction MOVAx (usually MOVAL) to move the address 
into the appropriate control block field. Thus, VAX MACRO expressions 
can be used. For instance, you can use a symbolic address to specify 
the control block address argument directly (for example, FAB=MYFAB, 
NAM=MYNAM, RAB=MYRAB, or XAB=MYXAB). 


You may also specify a register that contains the address using the form 
Rn, where 1 is a decimal number from 0 through 12. 


¢ For each argument that requires a nonkeyword data value, the store 
macro uses the VAX MACRO instruction MOVx to move data into the 
appropriate control block field. Thus, VAX MACRO expressions can be 
used. Note that a number sign (#) must precede a literal nonkeyword 
value, except when a literal value is enclosed within left angle ( <) and 
right angle (> ) brackets. However, if you specify the address where the 
argument value resides, a number sign must not precede the symbolic 
address nor the register expression that contains the address. 


e For binary option or keyword value fields, use the supplied keyword 
without a number sign and do not use a VAX MACRO expression. 
Multiple keyword arguments must be enclosed within left angle ( <) and 
right angle (> ) brackets. 
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In some cases, arguments are specified as run-time values using one of the 
following forms: 


e A VAX MACRO expression 


¢ The symbolic address of the argument value 


The format for each store macro is provided in Appendix B, which includes 
exceptions to the general rules previously described. 


Example 3-1 illustrates the use of the $XABDAT_STORE macro to set 
the creation date of the file to the beginning of a fiscal quarter, thereby 
establishing a valid starting date for the file data. 


Example 3—1_ Use of the $XABDAT and $XABDAT_STORE Macros 


.TITLE CREAT - SET CREATION DATE 
; Program that uses XABDAT and XABDAT_STORE 


.PSECT LONG WRT,NOEXE 
MYFAB: $FAB ALQ=500, FOP=CBT, FAC=PUT, - 
FNM=<DISK$: [PROGRAM] SAMPLE_FILE.DAT>, - 
ORG=SEQ, RAT=CR, RFM=VAR, SHR=NIL, MRS=52, XAB=MYXDAT 
MYXDAT: $XABDAT 


ATIM: .ASCID /9-AUG-1988 00:00:00.00/ 
BTIM: -BLKQ 1 


.PSECT CODE NOWRT,EXE 
.ENTRY CREAT, ~M<> 


START: $BINTIM_S TIMBUF=ATIM, TIMADR=BTIM ; Convert ASCII to binary time 
BLBC RO,SS_ERR ; Branch on error 
$XABDAT_STORE XAB=MYXDAT, CDT=BTIM ; Move time into XAB$Q_CDT 
$CREATE FAB=MYFAB ; Create file; populate 
BLBC RO, ERROR ; file later 

CLOSE: $CLOSE FAB=MYFAB ; Close file 
BRB FINI ; and exit 

ERROR: PUSHL FAB$L_STV+MYFAB ; Push FAB STS and 
PUSHL FAB$L_STS+MYFAB ; STV on stack 
CALLS #2, G°LIB$SIGNAL ; Signal error 
BRB FINI 

SS_ERR: PUSHL RO ; Push RO 
CALLS #1, G*LIB$SIGNAL ; Signal error 

FINI: RET 
.END CREAT 


This short program creates a file with a creation date of midnight, 

August 9, 1988. The FAB at symbolic address MYFAB defines a sequential 
file with variable-length records up to 52 bytes in length and specifies an 
allocation size of 500 blocks using the contiguous-best-try file processing 
option. It also specifies the file specification. The .ASCID assembler directive 
defines the constant date-time character string at symbolic address ATIM. 
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3.2.4 Service Macros 


The SYS$BINTIM system service is invoked to convert the constant ASCII 
time at symbolic address ATIM to binary format in the quadword at BTIM. 
The BTIM value is moved into the XAB$Q_CDT field of the XABDAT control 
block at symbolic address MYXDAT using the following XABDAT_STORE 
macro: 


$XABDAT_STORE XAB=MYXDAT, CDT=BTIM 


Because the creation date in field XAB$Q_CDT is input to the Create service 
($CREATE macro), the value must be stored before the program invokes the 
Create service. The file is created, then closed. Note that Create service errors 
are signaled using the FAB$L_STS and FAB$L_STV fields, not RO. 


The general macro format of VMS RMS service macros is described in Part I. 
Part III describes each service in detail, including the VAX calling format. 


Note that the general information applicable to invoking VMS RMS services 
in Chapter 2 also applies to programs written in VAX MACRO. 


The service macros use two general formats: 


1. label: macro-name 


2. label: macro-name RAB=rab-address, - 
ERR=entry,- 
SUC=entry 


The first format above takes no arguments. You supply the argument list 
within your program, and the argument pointer register (AP) is assumed to 
contain the address of the argument list. An example of this format is shown 
below. 


ARG_LOC: .BLKL 2 


MOVL #1,ARG_LOC ; Move number of args to ARG_LOC 
MOVAL INFAB, ARG_LOC+4 ; Move FAB address to ARG_LOC+4 
MOVAL ARG_LOC, AP ; Move ARG_LOC address to AP 
$OPEN ; Open file 


In this form, the $OPEN macro expands to the following VAX MACRO code: 
CALLG (AP), G°SYS$OPEN 


In the second format, you supply arguments that automatically generate an 
argument list on the stack according to the values you supplied. You specify 
these arguments using keywords, which can be in any order. You must 
separate keywords using a comma, a blank space, or tabs. The only argument 
required when using the second format is the control block address 
(FAB=fab-address or RAB=rab-address). This argument must be either a 
general register (RO through R11) containing the control block address, or a 
suitable address for a PUSHAL instruction. If you omit this argument, no 
other arguments are allowed; in other words, you must use the first format. 
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The ERR=entry and SUC=entry arguments are optional and, if used, provide 
the addresses of completion routine entry points. Completion routines are 
always executed as ASTs. VMS RMS places the values you supply in the 
argument list on the stack during execution of the expanded macro. These 
values must be addresses that can be used by a PUSHAL instruction. 


Here is an example of the second format: 
$OPEN FAB=INFAB 
This macro line expands to the following VAX MACRO code: 


PUSHAL INFAB 
CALLS #01, G°SYS$OPEN 


When the argument list contains a completion routine argument, an AST is 
queued. When the AST routine executes, the following conditions hold: 


* General registers RO through R11 are undefined. The AP contains the 
address of the AST argument list; the AST argument value in the AST 
argument list specifies the address of the associated control block (FAB or 
RAB). The status must be retrieved from the completion status code field 
(STS) of the associated control block. 


¢ Any general registers saved by an entry mask can be modified, in addition 
to RO and R1. 


e Additional calls to VMS RMS services can be made within the completion 
routines. 


¢ To exit from a completion routine, you must perform any necessary 
cleanup operations and execute a RET instruction. 

The calling format of each VMS RMS service is listed alphabetically in Part III. 

The format for the Close service is shown in the following code example: 

SYS$CLOSE fab ([,ferr] [,suc]] 


When you use a macro to call a service, remember to omit the “SYS” prefix. 
For example, use $CLOSE instead of SYS$CLOSE. 


All file-processing macros require the FAB address as an argument and 
optionally allow you to specify the entry points for error or success condition 
handlers, as shown in the following format illustration: 


$macro FAB=fab-addr [,ERR=error-entry] [,SUC=success-entry] 


For example, to invoke the $OPEN macro and pass it the FAB address of 
INFAB and the error entry point of OPEN_ERR, you could use the following 
macro: 


$OPEN FAB=INFAB, ERR=OPEN_ERR 


Note that the $RENAME macro has a different format, as noted in Table 3-3. 
This file processing macro has the following format: 


$RENAME OLDFAB=old-fab-addr [,ERR=error-entry] 
[,SUC=success-entry] ,NEWFAB=new-fab-addr 


3-11 


VMS RMS Macros and VAX MACRO Programming 
3.2 Using the VMS RMS Macros 


The format for record processing macros and block I/O macros requires the 
RAB address as an argument and optionally allows you to specify the entry 
points for error or success condition handlers, as shown in the following 
format illustration: 


$macro RAB=rab-addr [,ERR=error-entry] [,SUC=success-entry] 


Note that the $WAIT macro has a different format, in that it does not use the 
error and success arguments: 


$WAIT RAB=rab-addr 


Table 3-3 lists each service macro according to its macro type. 


Table 3-3 File, Record, and Block 1/O Processing Macros 
File Record 
Processing Processing Block 1/O 
$CLOSE $CONNECT $READ 
$CREATE $DELETE $SPACE 
$DISPLAY $DISCONNECT SWRITE 
SENTER $FIND 
$SERASE $FLUSH 
SEXTEND $FREE 
$NXTVOL $GET 
$OPEN $PUT 
$PARSE $RELEASE 
$REMOVE $REWIND 
SRENAME' $TRUNCATE 
$SEARCH $UPDATE 

SWAIT 


'Denotes macro with nonstandard format (see text). 


After calling a VMS RMS service, you should check the status code returned 
in RO (and the STS field of the appropriate control block). The recommended 
way to signal errors is to provide both the STS and STV fields of the FAB 

or RAB as arguments to the appropriate Run-Time Library routine. The 
following VAX MACRO instructions invoke the LIB$SIGNAL routine for a 
file-related (FAB) error using the CALLS (stack) form of calling a routine, 
where the FAB is located at symbolic address MYFAB (not shown): 


PUSHL MYFAB+FAB$L_STV 
PUSHL MYFAB+FAB$L_STS 
CALLS #2, G°LIB$SIGNAL 


; Push fields on stack 
; in reverse order 
; Invoke signal routine 
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VMS RMS Example Programs 


This section includes very brief examples illustrating the implementation of 
VMS RMS at the VAX MACRO programming level. See the Guide to VMS 
File Applications for VMS RMS examples using the File Definition Language 
(FDL) Utility. 


Using VMS RMS macros, you can create new files, process existing files, 
extend and delete files, and read, write, update, and delete records within 
files. 


To create and process VMS RMS files, your program must contain calls to 
appropriate VMS RMS services. Generally, you make these calls by using 
the VAX RMS service macros for run-time processing. When encountered 

at run time, the expanded code of these macros generates a call to the 
corresponding VMS RMS service. Each macro and its resultant call represent 
a program request for a VMS RMS file or record service, or a block I/O 
transfer operation. 





Creating, Accessing, and Deaccessing a File 


The Create service constructs a new file according to the attributes you 
specify in the FAB for the file, whereas the Open service makes an existing 
file available for processing by your program. Both of these services, invoked 
by the $CREATE and $OPEN macros respectively, allocate resources within 
the system to establish access (a path) to a file. You must open or create a 
file to perform most file operations and any record operations on that file. 
Applications designed for shared access must declare the type of sharing at 
this time. The user specifies the various types of shared access by setting bits 
in the file access control (FAB$B_FAC) and share (FAB$B_SHR) fields in the 
appropriate FAB. 


VMS RMS provides several file-processing options for the Create service. The 
create-if option (FAB$V_CIF option in the FAB$L_FOP field) requests that 
the file be created only if it does not exist. If the file does exist in the specified 
directory, the file is opened, not created. The Open and Create services both 
establish access to the desired file, but the Create service additionally allocates 
disk space and performs functions related to allocation. 


When you are finished processing a file, you invoke the Close service 
($CLOSE macro) to close the file, disconnect all record streams associated 
with the file and free all resources allocated to the file. If you do not explicitly 
invoke the Close service when the program image exits, VMS RMS attempts 
an implicit close. All resources associated with open files are returned when 
the files are deaccessed at image rundown time. However, process permanent 
files are not implicitly closed when an image exits. These are special files that 
the current CLI opens outside the context of a normal image. 
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4.1.1 Example of Opening and Creating Files 


Example 4-1 illustrates the use of the Open, Create, Connect, Get, Put and 
Close services to access and copy records from one file to another. Note 
that the arguments to the $FAB and $RAB macros are listed vertically on 
separate lines for ease in reading them. However, the argument list must 
be contiguous and a common programming error is omission of required 
delimiters and continuation characters when the arguments are listed in this 
manner. 


Example 4—1_ Use of the Create, Open, and Close Services 


.TITLE COPYFILE 
; This program copies the input file to the output file. 


.PSECT DATA, WRT, NOEXE 


INFAB: $FAB FNM = <INFILE:>,- ; Primary input file name 
DNM = <.INV> ; Default input file type 
INRAB: $RAB FAB = INFAB,-~- ; Pointer to FAB 
ROP = RAH,- ; Read-ahead option 
UBF = REC_BUFF, - ; Record buffer 
USZ = REC_SIZE ; and size 
OUTFAB: $FAB FNM = <QUTFILE:>,- ; Primary output file name 
, DNM = <.INV>,- ; Default output file name 
FOP = CTG,- ; Make contiguous file 
FAC = <PUT>,- ; Open for PUT operations 
SHR = <NIL>,- ; Exclusive file access 
MRS = REC_SIZE, - ; Maximum record size 
RAT = CR ; Implied carriage control 
OUTRAB: $RAB FAB = QUTFAB, - ; Pointer to FAB 
ROP = WBH,- ; Write-behind option 
RBF = REC_BUFF ; Output uses same buffer 
; as input 
REC_SIZE = 132 ; Maximum record size 
REC_BUFF : 
.BLKB  REC_SIZE ; Record buffer 


.PSECT CODE, NOWRT,EXE 
; Initialization - Open input and output files and connect streams 


.ENTRY COPYFILE, “M<R6> ; Save R6 

$OPEN FAB=INFAB ; Open input file 

BLBC RO, EXIT1 ; Quit on error 

$CONNECT RAB=INRAB ; Connect to input 

BLBC RO, EXIT2 ; Quit on error 

MOVL INFAB+FAB$L_ALQ, - ; Set proper size for output 
OUTFAB+FAB$L_ALQ 

$CREATE FAB=OUTFAB ; Create output file 

BLBC RO, EXIT3 ; Quit on error 

$CONNECT RAB=OUTRAB ; Connect to output 

BLBS RO, READ ; Branch to READ loop 

BRB EXIT4 ; Trap error 
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Example 4-1 
EXIT1: MOVAL 
BRB 
MOVAL 
BRB 
MOVAL 
BRB 
MOVAL 
BRB 


EXIT2: 
EXITS: 


EXIT4: 


; Copy records 
READ: $GET 
BLBS 
CMPL 
BEQL 
BRB 

WRITE: MOVW 
$PUT 
BLBC 
BRB 


; Close files, 


F_ERR: PUSHL 
PUSHL 
CALLS 
BRB 
PUSHL 
PUSHL 
CALLS 
$CLOSE 
$CLOSE 

_ RET 
.END 


R_ERR: 


DONE: 


EXIT: 


(Cont.) 


INFAB, R6 ; 
F_ERR ; 
INRAB, R6 ; 
R_ERR 
OUTFAB , R6 i 
F_ERR ; 
OUTRAB , R6 ; 
R_ERR ; 


Use of the Creat 


loop 


RAB=INRAB 
RO, WRITE , 
RO, #RMS$_EOF ; 
DONE 
EXIT2 ; 
INRAB+RAB$W_RSZ, - ; 
OUTRAB+RAB$W_RSZ 
RAB=OUTRAB 

RO, EXIT4 ; 
READ ; 


Signal any errors, and exit 


FAB$L_STV(R6) 
FAB$L_STS (R6) 
#2, G°LIB$SIGNAL ; 
EXIT 

RAB$L_STV(R6) ; 
RAB$L_STS (R6) ; 
#2, G°LIB$SIGNAL : 
FAB=INFAB ; 
FAB=OQUTFAB ; 


COPYFILE 


e, Open, and Close Services 


Error: Keep FAB address 
Signal file error 
Keep RAB address 


; Signal record error 


Keep FAB address 

Signal record error 

If error, retain RAB addr. 
Signal record error 


; Get a record 


Write the record 
Was error end-of-file? 


; Successful completion 


Error otherwise 
Input RAB sets record 


; Size for output RAB 
; Write the record 


Quit on error 
Go back for more 


; Push STV and STS of FAB 
; on the stack 


Signal error 


Push STV and STS of RAB 
on the stack 

Signal error 

Close input 

and output 

Return with status in RO 


This example illustrates how you can use the sequential file organization to 
create a new file by copying records from an existing file. The newly created 
file and the source file have variable-length records. 


This example assumes that an external program has identified the input file 
as a search list logical name using this statement: 


$ ASSIGN [INV]30JUN85, [INV.OLD]30JUN85 INFILE: 


This dictates that VMS RMS should look for the input file in directory [INV] 
first, and if it does not find the file, it should look in directory [INV.OLD]. 


The program also specifies the default file type INV for the input file using 


this statement: 


DNM=<. INV> 


; Def 


ault input file name 


Next the program configures the RAB used for the input file (labeled INRAB). 
The first argument links the RAB to the associated FAB (INFAB) and this is 
the only required argument to a RAB. The rest of the arguments specify the 
read-ahead option (described in later text) and the record buffer for the input 
file. The Get service uses the user record buffer address (UBF) field and the 
user record buffer size (USZ) field as inputs to specify the record buffer and 
the record size, respectively. 
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Note: When you invoke the GET service, RMS takes control of the record buffer 


and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 


The program then configures the FAB for the output file. The first argument 
uses the FNM field to equate the file name to the externally defined logical 
name OUTFILE. After the program specifies the default file specification 
extension for the output file, it specifies three additional FAB fields. 


First it specifies that VMS RMS should allocate contiguous space for the 
output file by setting the CTG bit in the FAB$L_FOP field of the FAB. 


Next the progam uses a program-defined variable to store the value 132 in 
the MRS field: 


MRS=REC_SIZE 
REC_SIZE= 132 


The program then specifies that each record is to be preceded by a line feed 
and followed by a carriage return whenever the record is output to a line 
printer or terminal: 


RAT=CR 


Because the program alternately reads and then writes each record, the input 
file and the output file may share the same buffer. However, because the 
Put service does not have access to the UBF and UBZ fields, the output RAB 
defines the buffer using the RBF and the RSZ fields. 


Note that the UBF, USZ, and RBF values are set prior to run time, but that 
the RSZ value is set at run time, just prior to invocation of the Put service. 
This is done because the input file contains variable-length records and the 
Put service relies on the Get service to supply each record’s size by way of 
the RSZ field, an INRAB output field. 


The following statement from the sample program illustrates this feature: 


WRITE: MOVW INRAB+RAB$W_RSZ, - ; Input RAB sets record 
OUTRAB+RAB$W_RSZ ; size for output RAB 


The run-time processing macros for the input file consist of a $OPEN, a 
$CONNECT, a $GET, and a $CLOSE macro. Because the input file already 
exists, the program accesses it with a $OPEN macro. The sole argument to 
this macro identifies the FAB to the Open service: 


$OPEN FAB=INFAB 


Next, the program connects a record stream to the input file by calling the 
Connect service and specifying INRAB as the appropriate RAB: 


$CONNECT RAB=INRAB 


Note that upon completion of each service call, the program tests the 
condition value in RO returned by the service before proceeding to the 

next call. If the call fails, the program exits with the appropriate control block 
address in R6. 


After creating the output file and establishing its record stream, the program 
begins a processing loop in which the Get service reads a record from the 
input file and the Put service writes the record to the output file. When all 
file records are copied, as indicated by the detection of the end of the file, the 
program exits to label DONE which closes both files. 
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The Close service disconnects the record stream for all RABs connected to 
the specified FAB. In a multistream environment (more than one RAB can 
be connected to a single FAB), a program may disconnect individual record 
streams using the Disconnect service. 


4.1.2 Example of Creating a Multiple-Key Indexed File 


Example 4-2 creates an indexed file on a remote DECnet node from a 
sequential file on the local node. The indexed file contains three keys. 


Example 4—2 Use of the Create Service for an Indexed File 


.TITLE CREATEIDX - CREATE INDEXED FILE 
IDENT /V001/ 


; This program creates an indexed file with three keys from a 
; sequential file containing a name and address list. The record 
; format of the input file is shown below: 


: First Name Column 00-10 

: Middle Initial Column 11-11 

; Last Name Column 12-26 

: Street Column 27-46 

City Column 47-58 

; State Column 59-60 

: Zip Code Column 61-65 

; Reserved for 

; new data Column 66-end of record 


; The input and output files are specified by the logical names SRC 
; and DST, respectively. For example: 


$ DEFINE SRC DBB1: [TEST] INPUT. DAT 

: $ DEFINE DST TRNTO: :DRA4: [RMS .FILES] OUTPUT .DAT 

; $ RUN CREATEIDX 

A ET ee eer OT Te ene Rear ene me re hr ert 
.SBITL Control block and buffer storage 
.PSECT DATA NOEXE , LONG 


; Define the source file FAB and RAB control blocks. 


SRC_FAB: 


$FAB FAC=<GET>, - ; File access for GET only 
FOP=<SQO0>, - ; DAP file transfer mode 
FNM=<SRC : > ; Name of input file 

SRC_RAB: 

$RAB FAB=SRC_FAB, - ; Address of associated FAB 
RAC=SEQ, - ; Sequential record access 
UBF=BUFFER, - ; Buffer address 
USZ=BUFFER_SIZE ; Buffer size 
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Example 4—2 (Cont.) Use of the Create Service for an Indexed File 


’ 


; Define the destination file FAB and RAB control blocks. 


DST_FAB: 


$FAB FAC=<PUT>, - ; File access for PUT only 
FOP=CTG, - ; Allocate contiguous 
FAC = <PUT>,- ; Open for PUT operations 
SHR = <NIL>,- ; Exclusive file access 
FNM=<DST: >, - ; Name of output file 
MRS=128, - ; Maximum record size 
RFM=VAR,, - ; Variable length records 
RAT=<CR> , - ; Implied carriage control 
ORG=IDX, - ; Indexed file organization 
XAB=DST_KEYO ; Address of start of XAB chain 

DST_RAB: 

$RAB FAB=DST_FAB, - ; Address of associated FAB 
MBF=3 , - ; Use 3 buffers 
RAC=KEY , - ; Random record writes 
RBF=BUFFER , - ; Buffer address 
ROP=LOA, - ; Specify initial fill size 
RSZ=BUFFER_SIZE ; Buffer size 


2 


; Define key definition XABs to describe the three keys. 


DST_KEYO: ; Primary key is Name 
$XABKEY REF=0, - ; Key reference number 
DAN=0, - ; Define data XABALL 
DFL=1536, - ; Define data fill of 75% 
ITAN=1,- ; Define index XABALL 
IFL=1536, - ; Jnitial<index fill 757 
PROLOG=3, - ; Request Prolog 3 
POS=<12,0,11>,- ; Segmented key: last name, 
SIZ=<15,1,1>,- ; first initial, middle initial 
NXT=DST_KEY1 ; Address of next XAB in chain 
DST_KEY1: ; ist alternate key is City 
$XABKEY REF=1, - ; Key reference number 
DAN=2, - ; Data level (SIDR) XABALL 
TAN=2,- ; Index XABALL 
IFL=768, - ; Initial index fill 75% 
POS=47, - ; Starting key position 
S1IZ=12, - ; Key size 
FLG=<CHG , DUP>, - ; Duplicates and changes 
NXT=DST_KEY2 ; Address of next XAB in chain 
DST_KEY2: ; 2nd alternate key is State 
$XABKEY REF=2, - ; Key reference number 
DAN=2, - ; Data level (SIDR) XABALL 
TAN=2,- ; Index XABALL 
IFL=768 , - ; Initial index fill 75% 
POS=59, - ; Starting key position 
FLG=<CHG , DUP>, - ; Duplicates and changes 
SIZ=2,- ; Key size 
NXT=DST_ALLO ; Designate next XAB 
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Example 4—2 (Cont.) Use of the Create Service for an Indexed File 


; Define allocation control XABs to define multiple areas 


DST_ALLO: 
$XABALL AID=0, - 
ALQ=328, - 
AOP=<CBT>, - 
BKZ=4, - 
DEQ=112, - 
NXT=DST_ALL1 
DST_ALL1: 
$XABALL AID=1,- 
ALQ=8 , - 
AOP=<CBT>, - 
BKZ=4, - 
DEQ=4, - 
NXT=DST_ALL2 
DST_ALL2: 
$XABALL AID=2, - 
ALQ=112, - 
AOP=<CBT>, - 
BKZ=2, - 
DEQ=38, - 
NXT=DST_ALL3 


; Data area definition 

; Allocation quantity and 

; contiguous best try 

; Bucket size of 4 blocks 

; Default extension quantity 
; Designate next XAB 


; Primary key index area 

; Allocation quantity and 

; contiguous best try 

; Bucket size of 4 blocks 

; Default extension quantity 
; Designate next XAB 


; Alternate key data area 

; Allocation quantity and 

; contiguous best try 

; Bucket size of 2 blocks 

; Default extension quantity 
; Designate next XAB 


; Allocate buffer to the size of the largest record being read. 


BUFFER: .BLKB 66 ; Buffer for input and output 
BUFFER_SIZE=.-BUFFER ; Buffer size 


CC OC OCC OC A CR ROR GOR GA OR I Ik kk a 2k 2k 4 a 2k 


.SBITL Mainline 
.PSECT CODE 


; Start of program 


-ENTRY CREATEIDX, ~M<R6> 


; Open the source and destination files. 


$OPEN FAB=SRC_FAB 


BLBC RO, EXIT1 
$CONNECT RAB=SRC_RAB 
BLBC RO, EXIT2 


$CREATE FAB=DST_FAB 
BLBC RO, EXITS 
$CONNECT RAB=DST_RAB 
BLBC RO, EXIT4 


BRB LOOP 
EXIT1i: MOVAL SRC_FAB , R6 
BRB F_ERR 
EXIT2: MOVAL SRC_RAB , R6 
BRB R_ERR 
EXIT3: MOVAL DST_FAB,R6 
BRB F_ERR 
EXIT4: MOVAL DST_RAB , R6 
BRB R_ERR 
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; Entry point 


; Open input file 

; Branch on failure 

; Connect input record stream 
; Branch on failure 

; Create output file 

; Branch on failure 

; Connect output record stream 
; Branch on failure 

; Bypass signaling code 

; Keep FAB address 

; Signal error 

; Keep RAB address 

; Signal error 

; Keep FAB address 

; Signal error 

; Keep RAB address 

; Signal error 
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Example 4—2 (Cont.) Use of the Create Service for an Indexed File 


; Transfer records until end-of-file is reached. 


LOOP: $GET RAB=SRC_RAB ; Read next rec from input file 


BLBS RO, PUT ; Branch on success 
CMPL RO, #RMS$_EOF ; Was it end-of-file (EOF)? 

BNEQ EXIT2 ; Branch if not EOF error 

BRB CLOSE ; Close and exit if EOF 

PUT: $PUT RAB=DST_RAB ; Write 66-byte record to output 

BLBS RO , LOOP ; On success, continue loop 

BRB EXIT4 ; On error, signal and exit 


; Close the source and destination files. 


F_ERR: PUSHL FAB$L_STV(R6) ; Push STV and STS fields 


PUSHL  FAB$L_STS(R6) ; on stack 
CALLS #2, G°LIB$SIGNAL ; Signal file error 
BRB EXIT ; Exit 
R_ERR: PUSHL RAB$L_STV(R6) ; Push STV and STS fields 
PUSHL RAB$L_STS(R6) ; on stack 
CALLS #2, G*LIB$SIGNAL ; Signal file error 
CLOSE: $CLOSE FAB=DST_FAB ; Close output file 
$CLOSE FAB=SRC_FAB ; Close input file 
EXIT:  $EXIT_S ; Exit 
. END CREATEIDX ; Specify starting address 


This example program creates an indexed file with a primary key and two 
alternate keys that are defined by appropriate key definition control blocks 
(XABKEY). For efficiency, the file is divided into areas consisting of a data 
area and an index area for each key using multiple allocation control blocks 
(XABALL). 


In each XABKEY, the DAN and IAN arguments (XAB$B_DAN and XAB$B_ 
IAN fields) indicate the area identification number (AID) of the corresponding 
XABALL. By setting the RAB$V_LOA bit in RAB field RAB$L_ROP, the 
program indicates that VMS RMS should use the DFL and IFL arguments 
(XAB$W_DFL and XAB$W_IFL fields) to determine the maximum initial fill 
size (in bytes) for data and index buckets (each bucket contains the number of 
blocks specified in the XABALL BKZ argument, XAB$B_BKZ field). 


These are the XABKEY and XABALL control blocks for the primary key (the 
NAME key) in this example: 


DST_KEYO: ; Primary key is Name 
$XABKEY REF=0, - ; Key reference number 
DAN=0, - ; Define data XABALL 
DFL=1536, - ; Define data fill of 75% 
ITAN=1,- ; Define index XABALL 
IFL=1536 , - ; Initial index fill 75% 
PROLOG=3, - ; Request Prolog 3 
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DST_ALLO: 
$XABALL AID=0, - ; Data area definition 
ALQ=328 , - ; Allocation quantity and 
AOP=<CBT>, - ; contiguous best try 
BKZ=4 , - ; Bucket size of 4 blocks 
DEQ=112, - ; Default extension quantity 
NXT=DST_ALL1 ; Designate next XAB 
DST_ALL1: 
$XABALL AID=1, - ; Primary key index area 
ALQ=8, - ; Allocation quantity and 
AOP=<CBT>, - ; contiguous best try 
BKZ=4 , - ; Bucket size of 4 blocks 
DEQ=4 , - ; Default extension quantity 
NXT=DST_ALL2 ; Designate next XAB 


The allocation information was obtained using the File Definition Language 
(FDL) editor which is especially useful when you are creating large indexed 
files. The DCL commands CREATE/FDL and CONVERT can be used to 
create files by using an FDL file produced by the FDL editor, without any 
programming. Instead of using the multiple XABs for the key definition and 
area allocations in this program, a simpler approach is to use the FDL file 
produced by the FDL editor by invoking the FDL routines FDL$PARSE and 
FDL$RELEASE (for more information on these routines, see the VMS Utility 
Routines Manual). 


Fixed-length records are copied from the sequential input file on the local 
node to the indexed file on the remote node. Each variable-length output 
record is initially 66 bytes long and may be extended to a maximum of 128 
bytes. A subsequent example in this document shows how to access this file 
using different key paths. 





4.2 Processing File Specifications 


The file name and file specification services, Parse and Search, are used for 
relatively complex operations such as processing wildcard characters. 


Before you can perform operations on a file, you must establish a path to 
the file. You do this by specifying the file specification string address and 
size (FAB$L_FNA and FAB$B_FNS) fields (and possibly the default file 
specification string address and size fields) of the FAB to describe an ASCII 
string within the program. In this ASCII string, you can have a concatenation 
of the network node name; a logical or device name; the directory name; and 
the file name, type, and version number. 


If a logical name is used, VMS RMS translates the logical name into 

its equivalent file specification before it applies defaults to any missing 
components of the file specification. If the logical name is a search list 
logical name, VMS RMS translates each element of the search list into an 
equivalent file specification before it applies defaults to that element. When 
using the Search service, a file specification that may contain a search list 
logical name must be handled as if wildcard characters were present in the 
file specification. 


The Parse service is required prior to the Search service in order to examine 
the file specification for wildcard characters or a search list. If the file is 
found, the Parse service sets a NAM block bit that VMS RMS uses internally 
and sets an appropriate value in the wildcard character context which is used 
as input by the Search service. The Parse service is invoked once, then the 
Search service is repetitively invoked as many times as there are files that 
match the original file specification. 


4-9 


VMS RMS Example Programs 


4.2 Processing File Specifications 


4—10 


If a wildcard is present, the Search service attempts to find all files that match 
the file specification. If an asterisk (*) is in the directory field, all directories 
on the specified device are searched for files that match the remaining file 
specification components. As with the use of wildcard characters, when a 
search list logical name is present, a single Parse service and multiple Search 
services return all files that match the file specification. With search lists, 
however, all list elements are searched for matching file specifications in 

the specified order without regard to uniqueness between the resulting file 
specifications. Search lists can be used in place of (or in addition to) wildcard 
characters to specify a more efficient search order, which can mean different 
combinations for the device, directory, file name, file type, and version 
number parts of a file specification. Search lists can also contain wildcard 
characters, if needed. 


In summary, the Parse and Search services use a search list logical name very 
much like a wildcard. Unlike the case of opening a file, in which the first 
instance where the file is found successfully ends the use of additional search 
list file specifications, the Parse and Search services use all search list file 
specifications. 


Example 4-3 shows how the $PARSE and $SEARCH macros can be used in 
wildcard processing. 


Example 4—3 Wildcard Processing Using Parse and Search Services 
.TITLE WILD 
; Program to accept wildcard characters in input (partial) file 


; specification and display full file specification. 


$NAMDEF ; NAM block definitions 
.PSECT DATA, NOEXE, WRT 
NAM_BLK: 
$NAM RSA=RES_STR, - ; Result buffer address 
RSS=NAM$C_MAXRSS, - ; Result buffer size 
ESA=EXP_STR, - ; Expanded buffer address 
ESS=NAM$C_MAXRSS ; Expanded buffer size 
FAB_BLK: 
$FAB FOP=NAM, - ; Use NAM block option 
NAM=NAM_BLK, - ; Pointer to NAM block 
FNA=INP_STR ; Addr of file name string 
EXP_STR: ; Expanded string buffer 
.BLKB NAM$C_MAXRSS 
RES_STR: ; Resultant string buffer 
.BLKB NAM$C_MAXRSS 
RES_STR_D: ; Resultant string descriptor 
.BLKL i 
.LONG RES_STR 
INP_STR: ; Input string buffer 
.BLKB NAM$C_MAXRSS 
INP_STR_D: ; Input string descriptor 


.LONG NAM$C_MAXRSS 
.LONG INP_STR 

INP_STR_LEN: ; Input string length 
.BLKL i 
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Example 4—3 (Cont.) Wildcard Processing Using Parse and Search 
Services 





PROMPT_D: ; User prompt string 
.ASCID /Please enter the file specification: / 


.PSECT CODE, EXE, NOWRT 
ENTRY WILD, “M<> 


PUSHAB INP_STR_LEN ; Address for string length 
PUSHAB PROMPT_D ; Prompt string descriptor 
PUSHAB INP_STR_D ; String buffer descriptor 
CALLS #3,G°LIB$GET_INPUT ; Get input string value 
BLBC RO, EXIT ; Quit on error 


; Store user input string and perform initial parse to 
; set up VMS RMS context for subsequent search. 


MOVB INP_STR_LEN, - ; Set string size 
FAB_BLK+FAB$B_FNS 

$PARSE FAB=FAB_BLK ; Parse the file spec 

BLBC RO, F_ERR ; Quit and signal on error 


; Search until all possibilities are exhausted. 
SEARCH_LOOP: 
$SEARCH FAB=FAB_BLK ; Find next file 
BLBC RO, SRCHERR ; Any more? 


; Print out the resultant string from the search operation 


MOVZBL NAM_BLK+NAM$B_RSL, - 


RES_STR_D ; Set string length 
PUSHAB RES_STR_D ; String descriptor 
CALLS #1,G°LIB$PUT_OUTPUT ; Output the result 
BLBC RO, EXIT ; Quit on error 
BRB SEARCH_LOOP ; Go for more 
SRCHERR : ; If the error is "No more 
CMPL RO, #RMS$_NMF ; files" then this is the 
BEQL S_EXIT ; normal completion of the 
; search loop. 
F_ERR: PUSHL FAB_BLK+FAB$L_STV ; Push STV and STS on stack 
PUSHL  FAB_BLK+FAB$L_STS ; in reverse order 
CALLS #2, G*LIB$SIGNAL ; Signal error 
S_EXIT: MOVL #1,RO ; Suppress "No More Files" 
EXIT: RET 
.END WILD 





This program is designed to locate all files corresponding to a partial file 
specification input. The program prompts the user for an input string, which 
can consist of a partial file specification, using the wildcard characters 
and/or any type of logical name, including a search list logical name. In 
many respects, this program emulates the DCL command DIRECTORY, 
which is discussed in the VMS DCL Dictionary. 


The program illustrates the use of the $PARSE and $SEARCH file name 
processing macros. Here is the program statement that invokes the Parse 
service for parsing the file name string: 


$PARSE FAB=FAB_BLK 
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Before invoking the Parse service ($PARSE macro), the program moves the 
input string length to the file name string (FAB$B_FNS) field. If the Parse 
service returns an error completion status, the program branches to the 
F_ERR error routine. 


Assuming no error, the program searches the disk directories specified by the 
expanded string area address field in the NAM block (NAM$L~_ESA) until all 
possible files conforming to the partial file specification input are found. Here 
is the program line that invokes the Search service: 


$SEARCH FAB=FAB_BLK 


A status test is performed immediately after the $$5EARCH macro. If an 
error is detected, the program branches to the SRCHERR label. If a no-more- 
files condition is detected, VMS RMS returns the RMS$_NMF message to 
indicate that all files that match the specification have been found. (This 
error, however, is not signaled.) 


This program contains two Run-Time Library routines: LIB{GET_INPUT and 
LIB$PUT_OUTPUT. The LIB$GET_INPUT routine inputs a record from the 
current controlling input device, specified by SYSSINPUT, using the VMS 
RMS Get service. The LIBSPUT_OUTPUT routine outputs a record (line) to 
the current controlling output device, specified by SYS$OUTPUT, using the 
VMS RMS Put service. Both routines are discussed in greater detail in the 
VMS Run-Time Library Routines Volume. 





4.3 Connecting and Disconnecting Record Streams 
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To associate or disassociate a file with one or more record streams, VMS RMS 
provides the Connect and Disconnect services, which are invoked using the 
$CONNECT and $DISCONNECT macros. 


Before reading and writing file records, the program must open (or create) 
the input and output files and then connect the files to the appropriate record 
streams by executing the $OPEN (or $CREATE) macro followed by the 
$CONNECT macro. 


Closing a file implicitly disconnects the record stream. Use the Disconnect 
service to explicitly disconnect a record stream that is not to be used 
immediately. This keeps the file open but releases various data structures 
for use by other processes until your program needs the record stream. 


Example 4-4 shows a program in which a user-entered reply determines 
which key path is selected to access the indexed file created in Example 4-2. 
The user-entered value determines the value specified for the RAB$B_KRF 
field. The RAB$B_ILRF value is set before the connect operation occurs 
because this field is input to the Connect service. 
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Example 4—4 Use of the Connect Service and Multiple Keys 





.TITLE MULTIKEY 
REC_SIZE=128 

.PSECT DATA NOEXE, LONG 
MODFAB: $FAB FNM=<DATA_OUTPUT . DAT>, - 
FAC=<GET> , - 
SHR=<GET, UPD, PUT>,- 
MRS=REC_SIZE 
FAB=MODF AB, - 
MBF=3, - 
UBF=REC_MODBUF , - 
USZ=REC_SIZE, - 


MODRAB: $RAB 


** RMS DATA ** 
; FAB file spec. 
; Get access needed 
; Allow Get, Update, Put 
; Specify record size 
; RAB; indicate FAB 
; Use 3 buffers 
; Specify buffer 


; Primary is default key 
; Record buffer 


TERMINAL I/O DATA ** 


/Enter list order: 1-by name, 2-by city, 3-by state, 9-end :/ 


Test value of menu answer 


2 means first alternate 

3 means second alternate 

9 means end program 

otherwise, display error message 
Entry error; retry 

Set key of reference in RAB 


Set key of reference in RAB 


Set key of reference in RAB 


KRF=0 
REC_START: . LONG REC_SIZE 
. ADDRESS REC_MODBUF 
REC_MODBUF : . BLKB REC_SIZE 
MPROO: .ASCID / / 
MPRO1: .ASCID 
ENTRYERR : .ASCID /* * Value entered must be 1, 2, 3, or 9. * */ 
REGANS: . LONG if 
.ADDRESS REGBUF 
REGBUF : . BLKB 1 
DONE:  .ASCID /Press RETURN to continue/ 
.PSECT CODE 
START: .WORD “M<> 
INPUT: PUSHAL MPROO ; Get input 
PUSHAL MPRO1 ; Display prompt 
PUSHAL REGANS 
CALLS #3, G°LIB$GET_INPUT 
BLBC RO, FINI 
CMPB #°A/1/,REGBUF : 
BEQLU PRIM ; 1 means primary 
CMPB #°A/2/,REGBUF ; Continue testing 
BEQLU = ALTi : 
CMPB #°A/3/,REGBUF ; Continue testing 
BEQLU) ALT2 : 
CMPB #°A/9/,REGBUF ; Continue testing 
BEQLU FINI ; 
BADANS: PUSHAL ENTRYERR ; 
CALLS #1, G*LIB$PUT_OUTPUT 
BLBC RO, FINI 
BRB INPUT ; 
PRIM: MOVB #0, MODRAB+RAB$B_KRF ; 
BRB OPEN 
ALT 1: MOVB #1, MODRAB+RAB$B_KRF ; 
BRB OPEN 
ALT2: MOVB #2 , MODRAB+RAB$B_KRF ; 
OPEN : $O0PEN FAB=MODFAB ; Open file 
BLBC RO, ERROR_OPEN 


$CONNECT RAB=MODRAB ; 
BLBC RO, ERROR 


Example 4—4 Cont’d. on next page 


Connect record stream 
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Example 4—4 (Cont.) 


NEXT: $GET 
CMPL 
BEQLU 
BLBC 
MOVZWL 
PUSHAL 
CALLS 
BLBS 
BRB 

CLEAN: $CLOSE 
BLBC 
PUSHAL 
CALLS 


ERROR_OPEN: 
PUSHL 
PUSHL 
CALLS 
BRB 

ERROR: PUSHL 
PUSHL 
CALLS 
$CLOSE 


FINI: RET 
. END 


RAB=MODRAB 
#RMS$_EOF , RO 
CLEAN 

RO, ERROR 


Use of the Connect Service and Multiple Keys 


: Get record 
; Test if EOF 


RAB$W_USZ+MODRAB,REC_START ; Set ASCII descriptor length 
; Display each record 


REC_START 

#1, G°LIB$PUT_OUTPUT 
RO, NEXT 

FINI 

FAB=MODFAB 

RO, ERROR_OPEN 

MPROO 

#1, G°LIB$PUT_OUTPUT 
RO, FINI 

DONE 

REGANS 

#2, G°LIB$GET_INPUT 
RO, FINI 

INPUT 


MODFAB+FAB$L_STV 
MODFAB+FAB$L_STS 
#2, G°LIB$SIGNAL 
FINI 
MODRAB+RAB$L_STV 
MODRAB+RAB$L_STS 
#2, G°LIB$SIGNAL 
FAB=MODFAB 


START 


; Repeat until EOF 
; Close file 


wee 


ous 


Error opening 

file. Signal error 
using LIB$SIGNAL. 
End program 
Record-related error 


; Signal error, then 


close file 


Here the SHR argument limits access to processes that perform the Get 
service, Put service, and Update service. If you anticipate no file modifications 
as your program accesses the file, you can improve performance by having the 
SHR argument limit access to processes that use the Get service (GHR=GET). 


Errors are signaled according to the recommended practice of using the 
FAB$L_STS and FAB$L_STV fields for file errors and RAB$L_STS and 
RAB$L_STV fields for record errors. 





4.4 Other File-Processing Operations 


Other VMS RMS file services include the Display, Erase, Extend, Remove, 
and Rename services, which can be invoked using the $DISPLAY, $ERASE, 
$EXTEND, $REMOVE, and $RENAME macros, respectively. 


Example 4-5 illustrates the use of the Rename service to rename a file from 
directory [USER] named NAMES.DAT to directory [USER.HISTORY] named 
OLD_NAMES.DAT. 
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Example 4—5 Use of the Rename Service 


.TITLE RENAME 


; Program that renames a file into a different directory and 


; displays the resultant string. 


.PSECT DATA,NOEXE, WRT 


; Define old FAB, old NAM, new FAB, new NAM, and buffers 


OLD_FAB: 


; Define old file FAB 
$FAB FNM=< [USER] NAMES . DAT>, - 
NAM=OLD_NAM ; Pointer to NAM block 
OLD_NAM: ; Define old file NAM 
$NAM ESA=EXP_OLD, - ; Equivalence string 
ESS=NAM$C_MAXRSS, - ; address and size 
RSA=RES_OLD, - ; Resultant string 
RSS=NAM$C_MAXRSS ; address and size 
NEW_FAB: ; Define new file FAB 
$FAB FNM=< [USER .HISTORY] OLD_NAMES. DAT>, - 
NAM=NEW_NAM ; Pointer to NAM block 
NEW_NAM: 
$NAM ESA=EXP_NEW, - ; Equivalence string 
ESS=NAM$C_MAXRSS, - ; address and size 
RSA=RES_NEW, - ; Resultant string 
RSS=NAM$C_MAXRSS ; address and size 
EXP_OLD: ; Old file equivalence 
.BLKB NAM$C_MAXRSS ; string buffer 
EXP_NEW: ; New file equivalence 
.BLKB NAM$C_MAXRSS ; string buffer 
RES_OLD: ; Old file resultant 
.BLKB NAM$C_MAXRSS ; string buffer 
RES_OLD_D: ; String descriptor 
.BLKL 1 
.LONG  RES_OLD 
RES_NEW: ; New file resultant 
.BLKB NAM$C_MAXRSS ; string buffer 
RES_NEW_D: ; String descriptor 
.BLKL 1 
.LONG RES_NEW 
MESS: .ASCID /has been successfully relocated to / 


.PSECT CODE,EXE, NOWRT 
.ENTRY RENAME, “M<> 
; Rename file 


$RENAME OLDFAB=OLD_FAB, NEWFAB=NEW_FAB 
BLBC RO, ERROR 
; Set up descriptors 


Example 4—5 Cont'd. on next page 
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Example 4—5 (Cont.) Use of the Rename Service 


MOVZBL OLD_NAM+NAM$B_RSL,RES_OLD_D 
MOVZBL NEW _NAM+NAM$B_RSL,RES_NEW_D 


PUSHAL RES_OLD_D ; Push resultant name, 
CALLS #1,G°LIB$PUT_OUTPUT ; display old file spec. 
BLBC RO, TERM_ERROR ; Branch on error 
PUSHAL MESS ; Push message on stack, 
CALLS #1,G°LIB$PUT_OUTPUT ; display message 
BLBC RO, TERM_ERROR ; Branch on error 
PUSHAL RES_NEW_D ; Push resultant name, 
CALLS #1,G°LIB$PUT_OUTPUT ; display new file spec. 
BLBS RO, DONE ; Branch on success 

TERM_ERROR: 
PUSHL RO ; Signal output error 
CALLS #1 ,G°LIB$SIGNAL ; from RO 
BRB DONE 

ERROR: PUSHL OLD_FAB+FAB$L_STV ; Push STV and STS on 
PUSHL  OLD_FAB+FAB$L_STS ; stack (reverse order) 
CALLS #2,G°LIB$SIGNAL ; Signal error 

DONE: RET 
.END RENAME 


This program uses the Rename service to change both the directory and the 
name of the object file, which is being replaced by a new file (created by a 
separate program). If the Rename service executes correctly, the resultant 
file specification of the old file, the message defined by the ASCII descriptor 
following the label MESS, and the resultant file specification of the new file 
are displayed as verification that the Rename service successfully completed. 





4.5 Retrieving and Inserting Records 
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The record-processing services provided by VMS RMS insert records into a 
file and retrieve records from a file. These services are the Find, Get, and 
Put services, which can be invoked by the $FIND, $GET, and $PUT macros, 
respectively. 


Example 4-6 illustrates the use of the $GET and $PUT macros. It connects 
the input and output record streams, reads a record from an indexed file, and 
writes the record to a relative file. The program illustrates the use of the key 
string buffer, the key string descriptor and the key string length when reading 
indexed records and it includes the use of a user prompt string. 
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Example 4-6 Use of the Get and Put Services 


.TITLE LOOKUP 
; This program looks up records in the input file and 
; writes the records to the output file. 


.PSECT DATA,WRT,NOEXE 


INFAB: $FAB FNM = <INFILE:>,- ; Input file logical name 

SHR = <GET,PUT,UPD,DEL> ; Allow read/write sharing 
INRAB: $RAB FAB = INFAB,- ; Pointer to FAB 

KBF = INP_STR,- ; Key buffer 

KRF = 0,- ; Primary key 

RAC = KEY,- ; Keyed access 

ROP = WAT,- ; Wait for record 

UBF = REC_BUFF, - ; Record buffer 

USZ = REC_SIZE ; and size 
OUTFAB: $FAB FNM = <OQUTFILE:>,- ; Output file logical name 

BKS = 3,- ; 3 blocks per bucket 

MRS = REC_SIZE, - ; Maximum record size 

ORG = REL,~- ; Relative file 

RAT = CR ; Implied carriage control 
OUTRAB: $RAB FAB = OUTFAB, - ; Pointer to FAB 

RBF = REC_BUFF ; Output uses same buffer 

; as input 
REC_SIZE = 132 ; Maximum size records 
REC_BUFF : 
.BLKB  REC_SIZE ; Record buffer 
INP_STR: ; Key string buffer 
.BLKB REC_SIZE 

INP_STR_D: ; Key string descriptor 


.LONG REC_SIZE 
.LONG INP_STR 

INP_STR_LEN : ; Key string length 
.BLKL = 1 

PROMPT_D: , User prompt string 
.ASCID /Please input key value: / 
.PSECT CODE, NOWRT,EXE 


; Initialization - Open input and output files and connect streams 


ENTRY LOOKUP, ~“M<> ; No registers to save 
$OPEN FAB=INFAB ; Open input file 
BLBC RO, EXIT1 ; Quit on error 
$CONNECT RAB=INRAB ; Connect to input 
BLBC RO, EXIT2 ; Quit on error 
$CREATE FAB=OUTFAB ; Create output file 
BLBC RO, EXIT3 ; Quit on error 
$CONNECT RAB=OUTRAB ; Connect to output 
BLBC RO, EXIT4 ; Quit on error 
BRB READ ; Skip error branching 
EXITi: MOVAL INFAB, R6 ; Keep INFAB address 
BRW F_ERR ; Signal FAB error 
EXIT2: MOVAL INRAB, R6 ; Keep INRAB address 
BRW R_ERR ; Signal RAB error 
EXIT3: MOVAL OUTFAB, R6 ; Keep OUTFAB address 
BRB F_ERR ; Signal FAB error 
EXIT4: MOVAL OUTRAB, R6 ; Keep OUTRAB address 
BRB R_ERR ; Signal RAB error 


Example 4—6 Cont'd. on next page 
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Example 4—6 (Cont.) 


Use of the Get and Put Services 





; Loop to copy records 


READ: 
PUSHAB 
PUSHAB 
PUSHAB 
CALLS 
BLBS 
CMPL 
BEQL 
BRB 

GET: MOVB 


$GET 
BLBS 
CMPL 
BEQL 
BRB 
PUT: MOVW 


$PUT 
BLBC 
BRB 


INP_STR_LEN 
PROMPT_D 

INP_STR_D 

#3 ,G°LIB$GET_INPUT 
RO, GET 

RO, #RMS$_EOF 

DONE 

EXIT 

INP_STR_LEN, - 
INRAB+RAB$B_KSZ 
RAB=INRAB 

RO, PUT 

RO, #RMS$_RNF 

READ 

EXIT2 
INRAB+RAB$W_RSZ, - 
OUTRAB+RAB$W_RSZ 
RAB=OQUTRAB 

RO, EXIT4 

READ 


; Close files and exit 


F_ERR: PUSHL 
PUSHL 
CALLS 
BRB 


R_ERR: PUSHL 
PUSHL 
CALLS 
DONE: $CLOSE 
$CLOSE 
EXIT: RET 
. END 


FAB$L_STV(R6) 
FAB$L_STS(R6) 
#2, G°LIB$SIGNAL 
EXIT 
RAB$L_STV(R6) 
RAB$L_STS(R6) 
#2, G°LIB$SIGNAL 
FAB=INFAB 
FAB=OUTFAB 


LOOKUP 


; Address for string length 

; Prompt string descriptor 

; String buffer descriptor 

; Get input string value 

; Quit on error or end-of-file 
; Was error end-of-file? 

; Successful completion 

; Error otherwise 

; Set key size 


; Get a record 

; Put if successful 

; No such record? 

; Try again 

; Error otherwise 

; Set the record size 
; for output 

; Write the record 

; Quit on error 

; Go back for more 


' Push STV and STS on 
; Stack in reverse order 
; Signal message 


; Push STV and STS on 

; stack in reverse order 

; Signal message 

; Close input 

; and output 

; Return with status in RO 


This program writes records from an existing indexed input file into a newly 
created relative output file. 


The program configures the file-sharing field (FAB$B_SHR) in the input FAB 
to permit sharing of the file by processes that use the Get, Put, Update and 


Delete services. 


The output FAB sets the bucket size field (FAB$B_BKS) at three blocks per 
bucket, limits the record size in the output file to 132 bytes, specifies the 

relative file organization and specifies an implicit carriage control when the 
file output is directed to a terminal. 


The RAB for the input file establishes the key data, sets the WAIT record 
option and defines the record buffer. The output RAB locates the record 
buffer. The rest of the first program section assigns values and allocates space 
to various program variables. After the program opens and creates the two 
files and connects the record streams, it executes a series of instructions at 
label READ that input the required key values and the user prompt. Then the 
program uses the $GET and $PUT macros to invoke the respective services 
for retrieving and inserting the records. The $GET macro uses the INRAB, 
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and the $PUT macro uses the OUTRAB as shown in the following program 
statements: 


$GET RAB=INRAB 
$PUT RAB=OUTRAB 


Each time the program reads or writes a record, it performs a status check. If 
the status check is successful, the program branches back to the READ label 
for the next record. If any of the status checks indicate an error, the program 
branches to the appropriate error handler before exiting. 


When the program completes the records transfers, it branches to the DONE 
label to close the record and exit. 





4.6 Deleting Records 


This service can only be used with relative and indexed files. Example 4-7 
illustrates use of the Delete service. 


Example 4—7 Use of the Delete Service 


.TITLE DELETE 


; This program looks up records in the input file and 
; deletes those records. 


» 


.PSECT DATA,WRT,NOEXE 


INFAB: $FAB FNM = <INFILE:>,- ; Input file logical name 
FAC = <DEL, GET> ; DEL access 
INRAB:  $RAB FAB = INFAB,- ; Pointer to FAB 
KBF = INP_STR, - ; Key buffer 
KRF = 0,- ; Primary key 
RAC = KEY ; Keyed access 
REC_SIZE = 132 ; Maximum size records 
INP_STR: ; Key string/record buffer 
.BLKB  REC_SIZE 
INP_STR_D: ; Key string descriptor 


.LONG REC_SIZE 
.LONG INP_STR 
INP_STR_LEN: ; Key string length 
.BLKL 1 
KEY_PMT_D: ; Key value prompt string 
.ASCID /Please enter key value: / 
.PSECT CODE, NOWRT,EXE 
; Initialization - Open file and connect stream 


’ 


ENTRY DELETE, “M<> ; No registers to save 
$OPEN FAB=INFAB ; Open input file 

BLBC RO, F_ERR ; Quit on error 
$CONNECT RAB=INRAB ; Connect to input 
BLBC RO, R_LERR ; Quit on error 


Example 4—7 Cont'd. on next page 
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Example 4—7 (Cont.) Use of the Delete Service 


’ 


; Delete record loop 


READ: 


PUSHAB INP_STR_LEN ; Address for string length 
PUSHAB KEY_PMT_D ; Prompt string descriptor 
PUSHAB INP_STR_D ; String buffer descriptor 
CALLS #3 ,G°LIB$GET_INPUT ; Get input string value 
BLBS RO, FIND ; Quit on error or end-of-file 
CMPL RO, #RMS$_EOF ; Was error end-of-file? 
BEQL DONE ; Successful completion 
BRB EXIT ; Error otherwise 

FIND: MOVB INP_STR_LEN, - ; Set key size 

INRAB+RAB$B_KSZ 

$FIND RAB=INRAB ; Locate the record 
BLBS RO, DEL ; Continue if found 
CMPL RO, #RMS$_RNF ; No such record? 
BEQL READ ; Try again 
BRB R_ERR ; Error otherwise 

DEL: $DELETE RAB=INRAB ; Delete the record 
BLBC RO,R_ERR ; Quit on error 
BRB READ ; Go back for more 


; Close files and exit 


F_ERR: PUSHL FAB$L_STV+INFAB ; Push STV and STS on 
PUSHL FAB$L_STS+INFAB ; stack in reverse order 
CALLS #2, G°LIB$SIGNAL ; Signal message 
BRB EXIT 

R_ERR: PUSHL RABS$L_STV+INRAB ; Push STV and STS on 
PUSHL RAB$L_STS+INRAB ; Stack in reverse order 
CALLS #2, G*LIB$SIGNAL ; Signal message 

DONE: $CLOSE FAB=INFAB ; Close files 

EXIT: RET ; Return with status in RO 


. END DELETE 





This program uses a key to find and delete a record. To use the $DELETE 
macro, the $FAB macro for the file must set the FAB$V_DEL bit as shown in 
the following code example: 


INFAB: $FAB FNM=<INFILE:>, - 
FAC=<DEL> 


The following program statement invokes the Delete Service and points to 
the input RAB: 


$DELETE RAB=INRAB 
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4.7 Updating Records 


Example 4-8 illustrates the use of the Update service. 


Example 4-8 Use of the Update Service 





. TITLE UPDATE 


; This program looks up records in the input file and 
; updates those records. 


.PSECT DATA, WRT, NOEXE 


INFAB: $FAB FNM = <INFILE:>, - ; Input file logical name 
FAC = <GET,UPD> ; Read and Write access 
INRAB: $RAB FAB = INFAB,- ; Pointer to FAB 
KBF = INP_STR, - ; Key buffer 
KRF = 0,- ; Primary key 
RAC = KEY,- ; Keyed access 
RBF = INP_STR ; Record buffer 
REC_SIZE = 132 ; Maximum size records 
INP_STR: ; Key string/record buffer 
.BLKB  =REC_SIZE 
INP_STR_D: ; Key string descriptor 


LONG REC_SIZE 
.LONG INP_STR 


INP_STR_LEN: ; Key string length 
»BLKL 4 

KEY_PMT_D: ; Key value prompt string 
.ASCID /Please input key value: / 

DATA_PMT_D: ; Data value prompt string 


.ASCID /Please input new record value: / 
.PSECT CODE, NOWRT , EXE 
; Initialization - Open file and connect stream 


, 


.ENTRY UPDATE, “M<> ; No registers to save 

$OPEN FAB=INFAB ; Open input file 

BLBC RO, FAB_E ; Quit on error 

$CONNECT RAB=INRAB ; Connect to input 

BLBC RO, RAB_E ; Quit on error 

BRB READ ; Begin update loop 
FAB_E: BRW F_ERR ; File (FAB) error 


RAB_E: BRW R_ERR ; Record (RAB) error 


; Update record loop 
READ: 


; Prompt for key value to look up. 


PUSHAB INP_STR_LEN ; Address for string length 
PUSHAB KEY_PMT_D ; Prompt string descriptor 
PUSHAB INP_STR_D ; String buffer descriptor 
CALLS #3,G°LIB$GET_INPUT ; Get input string value 

BLBS RO, FIND ; Quit on error or end-of-file 
CMPL RO, #RMS$_EOF ; Was error end-of-file? 

BEQL ALL_D ; Successful completion 

BRW EXIT ; Error otherwise 





Example 4—8 Cont'd. on next page 
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ALL_D: BRW DONE 


FIND: MOVB INP_STR_LEN, - ; Set key size 
INRAB+RAB$B_KSZ 
$FIND RAB=INRAB ; Locate the record 
BLBS RO ,UPD ; Continue if found 
CMPL RO, #RMS$_RNF ;: No such record? 
BEQL READ ; Try again 
BRB R_ERR ; Error otherwise 


; Prompt for new data record. 


UPD: 


PUSHAB INP_STR_LEN ; Address for string length 

PUSHAB DATA_PMT_D ; Prompt string descriptor 

PUSHAB INP_STR_D ; String buffer descriptor 

CALLS #3,G°LIB$GET_INPUT ; Get input string value 

BLBC RO, EXIT ; Quit on error 

MOVW INP_STR_LEN, - ; Set record size 
INRAB+RAB$W_RSZ 

$UPDATE RAB=INRAB ; Write the record 

BLBC RO,R_ERR ; Quit on error 

BRW READ ; Go back for more 


; Close files and exit 


F_ERR: PUSHL FAB$L_STV+INFAB ; Push STV and STS on 
PUSHL FAB$L_STS+INFAB ; stack in reverse order 
CALLS #2, G°LIB$SIGNAL ; Signal message 
BRB EXIT 

R_ERR: PUSHL RAB$L_STV+INRAB ; Push STV and STS on 
PUSHL RAB$L_STS+INRAB ; stack in reverse order 
CALLS #2, G°LIB$SIGNAL ; Signal message 

DONE: $CLOSE FAB=INFAB ; Close files 

EXIT: RET ; Return with status in RO 


. END UPDATE 


This program uses a key and a new record entered from the terminal to 
update a record in the input file. 


To use the $UPDATE macro, the $FAB macro for the file must specify that 
the FAB$V_UPD bit is marked in the file access (FAB$B_FAC) field as shown 
in the following code example: 


INFAB: $FAB  FNM=<INFILE:>, - 
FAC=<GET , UPD> - 


Before updating a record, the program uses the Find service to locate the 
record by executing the $FIND macro located at the FIND label. . 


$FIND RAB=INRAB 


4.8 
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In addition to the major types of record access provided by the sequential, 
random by key value or relative record number, and random by RFA access 
modes, VMS RMS provides another means to access data in a file: block I/O. 


Block I/O operations let you directly read or write the blocks of a file. These 
operations are provided for users who must keep system overhead to a 
minimum and need no interpretation of file data as logical records, yet still 
want to take advantage of the easy file access of VMS RMS. Block I/O is an 
intermediate step between the VMS RMS record operations and direct use of 
VMS $QIO system services. 


The three block I/O services are invoked using the $READ, $SPACE, and 
$WRITE macros, respectively. 


¢ The Read service transfers a specified number of bytes to memory. 


e The Space service positions a file forward or backward a specified number 
of blocks. 


¢ The Write service writes a specified number of bytes to a file. 


The Read and Write services always begin on a block boundary. 


In addition to the Read, Space, and Write services, you can use the following 
services on a record stream connected for block I/O operations: 


e The Disconnect service (6DISCONNECT macro) 
e The Flush service (§$FLUSH macro) 

¢ The Next Volume service (SNXTVOL macro) 

¢ The Rewind service (6REWIND macro) 


These services perform miscellaneous operations or disconnect the record 
stream. They do not work on the contents of the records themselves. 


You cannot perform block I/O operations on shared files. That is, file access 
for block I/O operations is denied unless the FAB$V_UPI or the FAB$V_NIL 
bit is set in the FAB$B_SHR field. 


You specify block I/O operations for a record stream by setting the FAB$V_ 
BIO bit in the file access (FAB$B_FAC) field as input to the Open or Create 
services. If you intend to write to the file, you must set the PUT option in the 
FAB$B_FAC field; if you intend to read from the file, you must set the GET 
option in the FAB$B_FAC field. Setting the FAB$V_BIO bit when you are 
creating a relative or indexed file causes VMS RMS to omit prolog processing 
for indexed files and initial space prezeroing in relative files. 


For files of unknown organization, block I/O is the only form of processing 
allowed. Processing proceeds identically to that for block I/O to the relative 
file organization described above. 
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4.8.1 Mixed Block and Record I/O 


4-24 


How and when VMS RMS allows you to switch between record I/O and 
block I/O depends on the organization of the file being accessed. 


When you access sequential files, VMS RMS allows you to switch between 
record I/O and block I/O with each record operation, if desired. To enable 
I/O switching for a record stream connected to a sequential file, use the 
following procedure: 


1 Set the FAB$V_BRO option in the FAB$B_FAC field as input to the 
Create or Open service. 


2 Clear the RAB$L_ROP field RAB$V_BIO option as input to the Connect 
service. 


This procedure informs VMS RMS that it should check the RAB$V_BIO 
option in the RAB$L_ROP field after each operation. 


To do a block I/O operation: 
1 Set the RAB$L_ROP field RAB$V_BIO option. 
2 Invoke a VMS RMS block I/O service (Read, Space, or Write). 


To do a record I/O operation: 
1 Clear the RAB$L_ROP field RAB$V_BIO option. 
2 Invoke a VMS RMS record I/O service. 


Use care if you do choose to mix record and block I/O operations for 
sequential files. When you switch operations on disk devices, the context 

of the current record, the next record, and the next block pointer is undefined. 
Thus, the first operation after the switch must not use sequential record access 
mode. For magnetic tape devices, the context of the next record or next block 
indicates the start of the following block on the tape for the first operation 
after the switch. 


As previously noted, you usually set the FAB$B_FAC field FAB$V_BRO 
option only to indicate to VMS RMS that you want to mix record I/O and 
block I/O operations. If you decide that you want to perform block I/O 
processing only, you can set the RAB$L_ROP field RAB$V_BIO option after 
you open the file but before you invoke the Connect service. This connect- 
time operation overrides the setting of the FAB$V_BRO option for the current 
record stream and indicates to the Connect service that you only intend to 
do block I/O for this file, thus eliminating the need to allocate internal I/O 
buffers. (However, you must still allocate buffers for block I/O operations 
in your application program.) If you set the FAB$V_BRO option when you 
create an indexed file, the key definition XABs for that file must be present. 


When you access relative or indexed files, switching is available only if you 
close and reopen the file. VMS RMS does not permit both types of I/O 
simultaneously. When multiple record streams are used, all record streams 
must use the same type of I/O, either record I/O or block I/O. 


You specify the I/O type when you create or open a file by either selecting 
the block I/O option (FAB$V_BIO bit set) or by selecting record I/O (FAB$V_ 
BIO bit clear). For relative and indexed files, the decision to use block I/O or 
record I/O for a file can be postponed, if desired, until the record stream is 
connected by the following procedure: 
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1 Set the FAB$B_FAC field FAB$V_BRO option when you are opening (or 
creating) the file. 


2 Indicate the appropriate operation to the Connect service by either setting 
the RAB$V_BIO bit in the RAB$L_ROP for block I/O or by clearing it 
for record I/O. 


4.8.2 The Next Block Pointer (NBP) 


For block I/O operations to sequential files on disk devices, VMS RMS 
maintains an internal next block pointer (NBP) that does the following 
functions: 


e Points to the beginning of the file following execution of a Connect 
service if the RAB$V_EOF option in the RAB$L_ROP field of the RAB 
is cleared. If the RAB$L_ROP field RAB$V_EOF option is set, the NPB 
points to the block following the end of file. The RAB$V_EOF option is 
relevant only for sequential files doing block I/O processing. 


e Points to the block following the highest numbered block transferred by a 
read or write operation. 


¢ Points to the next block following an operation invoked by the Space 
service. 


An explicit Extend service is required for relative and indexed files because 
VMS RMS does not automatically extend a file’s allocation when using block 
I/O processing. 


Example 4-9 illustrates how to copy a file using block I/O. 
Example 4-9 Use of Block I/O 


TITLE BLOCKIO 
; This program copies the input file to the output file. 
; It illustrates block I/0 using the VMS RMS $READ and $WRITE 


» macros. 


.PSECT DATA,WRT,NOEXE 


INFAB: $FAB FNM = <INFILE:>, - ; Input file name 
FAC = <BI0,GET> ; Block I/0 read operations 
INRAB: $RAB FAB = INFAB, - ; Pointer to FAB 
BKT = 0,- ; Start with current block 
UBF = REC_BUFF, - ; Record buffer 
USZ = REC_SIZE : and size 
OUTFAB: $FAB FNM = <OUTFILE:>,- ; Output file name 
FOP = CBT,- ; Try for contiguous file 
MRS = REC_SIZE, - ; Maximum record size 
FAC = <BIO,PUT>,- ; Block I/0 write operations 
RAT = CR ; Implied carriage control 
OUTRAB: $RAB FAB = OUTFAB, - ; Pointer to FAB 
BKT = 0,- ; Start with current block 
RBF = REC_BUFF ; Output uses same buffer 
; as input 
REC_SIZE = 1024 ; Maximum record size 


Example 4—9 Cont'd. on next page 
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Example 4—9 (Cont.) 


REC_BUFF : 


.BLKB REC_SIZE 


.PSECT CODE, NOWRT, EXE 


Use of Block I/O 


; Record buffer 


; Initialization - Open input and output files and connect streams 


ENTRY BLOCKIO,“M<> 


$OPEN FAB=INFAB 
BLBC RO, EXIT1i 
$CONNECT RAB=INRAB 


BLBC RO, EXIT2 

MOVL INFAB+FAB$L_ALQ, - 
OUTFAB+FAB$L_ALQ 

$CREATE FAB=OUTFAB 

BLBC RO, EXIT3 

$CONNECT 

BLBC RO, EXIT4 


RAB=OUTRAB 


; Copy loop 


READ: 


WRITE: 


; Error 


EXIT1: 
EXIT2: 
EXITS: 
EXIT4: 
; Close 
DONE: 


EXIT: 


$READ  RAB=INRAB 

BLBS RO, WRITE 

CMPL RO, #RMS$_FOF 

BEQL DONE 

BRB EXIT2 

MOVW INRAB+RAB$W_RSZ, - 
OUTRAB+RAB$W_RSZ 

$WRITE RAB=OUTRAB 

BLBC RO, EXIT4 

BRB READ 


Signaling 


MOVL INFAB+FAB$L_STS ,R2 
MOVL INFAB+FAB$L_STV ,R3 
BRB EXIT 
MOVL INRAB+RAB$L_STS ,R2 
MOVL INRAB+RAB$L_STV ,R3 
BRB EXIT 
MOVL OUTFAB+FAB$L_STS, R2 
MOVL OUTFAB+FAB$L_STV,R3 
BRB EXIT 
MOVL OUTRAB+RAB$L_STS , R2 
MOVL OUTRAB+RAB$L_STV , R3 
BRB EXIT 


files and exit 


$CLOSE FAB=INFAB 

$CLOSE FAB=OUTFAB 

RET 

PUSHL = R3 

PUSHL R2 

CALLS #2, G°LIB$SIGNAL 
RET 


. END BLOCKIO 


; No registers to save 
; Open input file 

; Quit on error 

; Connect to input 

; Quit on error 

; Set proper size 


for output 


; Create output file 
; Quit on error 

; Connect to output 
; Quit on error 


; Get a block 

; Write the block 

; Was error end-of-file? 
; Successful completion 


If not, signal error 


; Set the record size 


for output 


; Write the block 
; Quit on error 
; Go back for more 


; Move STS into R2 
; Move STV into R3 
; Signal error 
; Move STS into R2 
; Move STV into R3 
; Signal error 
; Move STS into R2 
; Move STV into R3 
; Signal error 
; Move STS into R2 
; Move STV into R3 
; Signal error 


; Close input and 


output files 


; Return w/ success in RO 
; Push STV and STS 

; on stack 

; Signal error 

; Return w/ status in RO 
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This example program uses block I/O to transfer the contents of the input file 
to the output file. The following program data statements specify block I/O 
read operations from the input file by setting the FAB$V_BIO bit (block I/O) 
and the FAB$V_GET bit (read) in the FAB$B_FAC field of the input file’s 
FAB: 


INFAB: $FAB FNM 
FAC 


<INFILE>, - ;Input file name 
<BIO,GET>, - 


The following data statements specify block I/O write operations to the 
output file by setting the FAB$V_BIO bit (block I/O) and the FAB$V_PUT bit 
(write) in the FAB$B_FAC field of the output file’s FAB: 


OUTFAB: $FAB FNM 
FAC 


<INFILE>, - ;Output file name 
<BIO,PUT>, - 


“ool 


The input file’s contents are copied until the end of file is encountered. Any 
errors are signaled with the convention of using both the STS and STV fields 
of the appropriate control block. 





Other Record-Processing Operations 


See Part III for details of VMS RMS record services not discussed in this 
chapter, including the Flush, Free, Next Volume, Release, Rewind, and 
Wait services. A process invokes these services using the $FLUSH, $FREE, 
$NXTVOL, $RELEASE, $REWIND, and $WAIT macros, respectively. 





Control Routines 


In addition to the general- and special-purpose file-processing macros, VMS 
RMS provides three control routines for processing files. These routines are 
identified by the following entry point names: 


e SYSSRMSRUNDWN 
¢ SYS$SETDDIR 
¢ SYS$SETDFPROT 


These routines do not reference fields in user control blocks and are not called 
with a macro. Instead, you provide an argument list and call VMS RMS at 
the entry point for the routine. None of these routines is widely used, and 
none is essential to normal VMS RMS file and record processing. 


For information on these routines, see the VMS System Services Reference 
Manual. 





VMS RMS Control Blocks 


Part Il describes each VMS RMS control block, including a complete listing 
and description of each field. 


5.1 


File Access Block (FAB) 


The file access block (FAB) defines file characteristics, file access, and certain 
run-time options. It also indicates whether other control blocks are associated 
with the file. 





Summary of Fields 


Table 5—1 FAB Fields 


Certain FAB fields are directly equivalent to certain File Definition Language 
(FDL) attributes. For information about FDL, refer to the VMS File Definition 
Language Facility Manual. 


The symbolic offset, size, FDL equivalent, and a brief description of each FAB 
field are presented in Table 5-1. 





Field Offset aS FDL Equivalent Description 

FAB$SL_ALOQ 4 FILE ALLOCATION Allocation quantity (blocks) 

FAB$B_BID' 1 None Block identifier 

FAB$B_BKS 1 FILE BUCKET_SIZE Bucket size 

FAB$B_BLN' 1 None Block length 

FABS$W-_BLS 2 FILE MT_BLOCK_SIZE Magnetic tape block size 

FAB$V_CHAN_MODE_ -? None Channel access mode 
protection 

FABS$L_CTX 4 FILE CONTEXT Context 

FABS$W_DEQ 2 FILE EXTENSION Default file extension quantity 

FAB$L_DEV? 4 None Device characteristics 

FABSL_DNA 4 FILE DEFAULT_NAME Default file specification string 
address 

FAB$B_DNS 1 FILE DEFAULT_NAME Default file specification string 
size 

FAB$B_FAC 1 ACCESS* File access 

FAB$L_FNA 4 FILE NAME File specification string address 

FABSB_FNS 1 FILE NAME File specification string size 

FAB$L_FOP 4 FILE* File-processing options 

FAB$B_FSZ 1 RECORD CONTROL _FIELD_SIZE Fixed-length control area size 

FAB$W_GBC 2 FILE GLOBAL__BUFFER_COUNT Global buffer count 


'This field is statically initialized by the $FAB macro to identify this control block as a FAB. 


2This is a 2-bit field. 


3This field cannot be initialized by the $FAB macro. 


4This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 5—1 (Cont.) 


Field Offset 


FABSW_IFIP 
FAB$V_LNM_MODE 


FABSL_MRN 
FAB$W_MRS 
FAB$L_NAM 
FAB$B_ORG 
FAB$B_RAT 
FAB$B_RFM 
FAB$B_RTV 
FAB$L_SDC? 


FAB$B_SHR 

FAB$L_STS? 
FAB$L_STV? 
FAB$L_XAB 


2This is a 2-bit field. 


3This field cannot be initialized by the $FAB macro. 


FAB Fields 

Size 

(Bytes) FDL Equivalent Description 

Z None Internal file identifier 

# None Logical name translation access 
mode 

4 FILE MAX __RECORD_NUMBER Maximum record number 

2 RECORD SIZE Maximum record size 

4 None Name block address 

1 FILE ORGANIZATION File organization 

1 RECORD* Record attributes 

1 RECORD FORMAT Record format 

1 FILE WINDOW_SIZE Retrieval window size 

4 None Secondary device 
characteristics 

1 SHARING* File sharing 

4 None Completion status code 

4 None Status values 

4 None Extended attribute block 


address 


4This field contains options; corresponding FDL equivalents are listed in the description of the field. 


Each FAB field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations on remote files with a VMS system as 


the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


To use a FAB, you must allocate process storage and specify the character 
string for the primary file specification and, optionally, the default file 
specification. The FAB$L_FNA and FAB$B_FNS fields define the primary 
file specification to VMS RMS; the FAB$L_DNA and FAB$B_DNS fields 
define the default file specification to VMS RMS. 


The format and arguments of the $FAB macro and the $FAB_STORE macro 
are defined in Appendix B. 
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5.2 FABS$L_ALO Field 


The allocation quantity (ALQ) field defines the number of blocks to be 
initially allocated to a disk file when it is created (using a Create service) or to 
be added to the file when it is explicitly extended (using an Extend service). 
This field corresponds to the FDL attribute FILE ALLOCATION. 


This field contains a numeric value in the range of 0 through 4,294,967,295, 
although the maximum value depends on the number of blocks available on 
the device to be used. A value of 0 indicates no allocation. 


When you create a new file using the Create service, VMS RMS interprets the 
value in the FAB$L_ALQ field as the number of blocks for the initial extent 
of the file. If the value is 0, the minimum number of blocks for the specific 
file organization is the allocation quantity used for the initial extent. For 
example, in indexed files, only the number of blocks necessary to contain key 
and area definitions is used as the initial extent quantity when FAB$L_ALQ 
is 0. 


When VMS RMS opens an existing file, it sets the FAB$L_ALQ field to 
indicate the highest virtual block number currently allocated to the file. 


When you use the Extend service, this field specifies the number of blocks to 
be added to the file. Note that VMS RMS uses this value as the extension 
value when a process extends a file using the Extend service unless the 
process changes the value before it invokes the Extend service. 


Note that the value 0 is not acceptable for extending a file. 


When you use the Create and Extend services, the allocation quantity value is 
rounded up to the next disk cluster boundary; the number of blocks actually 
allocated is returned in the FAB$L_ALQ field. 


Note that the function of the FAB$L_ALQ field with the Create and Extend 
services changes if allocation control XABs are present during the operation. 
The description of the XABALL control block (see Chapter 8) discusses 
allocation control XABs and their effect on the FAB$L_ALQ field during file 
creation or extension. 





5.3 FAB$B_BID Field 


The block identifier (BID) field is a static field that identifies a control block 
as a FAB. Once set, this field should not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
FAB$C_BID (this is done by the $FAB macro). 


5.4 FAB$B_BKS Field 


The bucket size (BKS) field is used only for relative or indexed files to specify 
the number of blocks in each bucket of the file. 


This field contains a numeric value in the range of 0 to 63. If you do not 
specify a value or specify a value of 0, VMS RMS uses a default of the 
minimum number of blocks needed to contain a single record, or a minimum 
of two records for indexed files. If the file will be processed by RMS-11, the 
bucket size must be less than or equal to 32 blocks. 


5.5 


File Access Block (FAB) 
5.4 FAB$B_BKS Field 


When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Also, certain record types contain 
control bytes; thus, the number of records per bucket multiplied by the 
number of control bytes per record equals the number of record overhead 
bytes per bucket. See the Guide to VMS File Applications for more information. 


Before specifying a bucket size, you must be aware of the relationship 
between bucket size and record size. You must also consider any record 
control bytes (overhead) required by VMS RMS for the type of record chosen. 
Because VMS RMS does not allow records to cross bucket boundaries, you 
must ensure that the number of blocks per bucket conforms to formulae 
designed to handle one of the following: 


¢ Relative files with fixed-length records 

e Relative files with variable-length records 

e Relative files with VFC (variable with fixed control) records 
e Indexed files with fixed-length records 


e Indexed files with variable-length records 


You can use the Edit/FDL Utility to determine the optimum bucket size. 
Note that if an allocation control XAB is specified, the value specified in the 
XAB$B_BKZ field supersedes the value specified in the FABSB_BKS field. 
When multiple allocation control XABs are specified, the largest value in any 
XAB$B_BKZ field supersedes the value in the FAB$B_BKS field. Refer to 
Chapter 8 for information about the XAB$B_BKZ field. 


When you open an existing relative or indexed file, VMS RMS sets the 
FAB$B_BKS field to the defined size of the largest bucket size in the file. 
However, when you create a new relative or indexed file, set the FAB$B_BKS 
field before you invoke the Create service rather than use the default. 


With indexed files, note that if the FAB$B_BKS field is not specified and a 
maximum record size (FAB$W_MRS field) is specified, then VMS RMS selects 
a bucket size that allows at least one maximum size record to fit. Generally, 
performance for record insertion and sequential retrieval on the primary key 
improves if at least six or seven data records fit into a primary data bucket. 

If either the bucket size or the disk cluster size is other than one block, use a 
default extension quantity (FAB$W_DEQ) that is the least common multiple 
of the bucket size and cluster size to avoid allocated but unused blocks within 
the file. 


This field corresponds to the FDL attribute FILE BUCKET_SIZE. 





FAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
FAB. Once set, this field should not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic value FAB$C_ 
BLN (this is done by the $FAB macro). 
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5.6 FABS$W_BLS Field 


VMS RMS uses the block size (BLS) field as input for nondisk files. The 
BLS field usually defines the size, in bytes, of the blocks on a magnetic tape. 
Note that for some devices, this value must be an even number. This field 
corresponds to the FDL attribute FILE MT_BLOCK-_SIZE. 


The FAB$W_BLS field contains a numeric value in the range of 20 through 
65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes. 
(Foreign tapes are those that are not in the standard ANSI format used by 
the VMS operating system and must be mounted using the DCL command 
MOUNT/FOREIGN.) If no value or a value of 0 is specified, the default 
selected when the volume was mounted is used. 


When you create a magnetic tape file, you can set the FAB$W_BLS field 
before you invoke the Create service. In all other cases, VMS RMS ignores 
this field. When you open an existing sequential file with an Open service, 
VMS RMS returns the device buffer size. For terminals, this field defines the 
WIDTH setting; for mailboxes, this field defines the maximum message size. 


For compatibility with RMS—11, VMS RMS always rounds off the block size 
for an ANSI-formatted tape to the next highest multiple of 4. For example, 
if you set the block length to 38, VMS RMS sets it to 40. The block size of a 
foreign tape is not rounded off by VMS RMS. 


To create a magnetic tape for interchange with DEC operating systems other 
than VMS, consult the documentation for the recipient system to identify 
possible limitations on block size. ANSI standards require that the block size 
be less than or equal to 2048 bytes. 


5.7. FABSV_CHAN_MODE Subfield 


The channel access mode protection (CHAN—MODE) subfield is the 
component part of the FAB$B_ACMODES field that specifies the access 
mode in which the requested channel is assigned. VMS RMS ignores this 
2-bit field unless the process first sets either the FAB$V_UFO bit or the 
FAB$V_NFS bit in the FAB$L__FOP field. 


The FAB$V_CHAN—MODE subfield may contain one of the four values 
listed below with the related constant value for each shown in parentheses. 
O None 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 

3 User mode (PSL$C_.USER) 


The default value is 0 (none), which is interpreted by VMS RMS as executive 
mode. 


If the access mode requested is more privileged than the access :node of the 
calling process, VMS RMS uses the access mode of the caller and does not 

return an error. For more information about logical name concepts, see the 

VMS System Services Volume. 


There is no corresponding FDL equivalent for this field. The FAB$V_CHAN_ 
MODE subfield is used locally for channel to DECnet communications but is 
ignored on the remote system. 
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To set this field from MACRO level, you include the appropriate expression as 
an argument to the $FAB macro. For example, to specify supervisor channel 
access mode, you might include a statement in this format: 


$FAB ...,CHAN_MODE = PSC$C_SUPER,... 


From a high-level language, refer to your documentation as to how (and 
whether) you can directly access VMS RMS fields and then incorporate the 
appropriate channel access mode expression into the appropriate language 
statement. 





FABS$L_CTX Field 


The user context (CTX) field allows you to convey user information to a 
completion routine in your program. This field contains a user-specified 
value, up to four bytes long, and is intended solely for your use. VMS RMS 
never uses it for record management activities. 


This field corresponds to the FDL attribute FILE CONTEXT. 





FAB$W_DEO Field 


The default file extension quantity (DEQ) field specifies the number of blocks 
to be added when VMS RMS automatically extends the file. Automatic 
extension only applies to files that reside on disk devices and occurs whenever 
your process invokes a Put or Write service and the currently allocated file 
space is exhausted. When you invoke a Put service, automatic file extension 
occurs when needed, regardless of the file organization. When you invoke 
the Write service, automatic extension occurs only for sequential files (indexed 
and relative files require the Extend service to extend file allocation). 


This field corresponds to the FDL attribute FILE EXTENSION. 


This field contains a numeric value in the range 0 through 65,535, which 

is rounded up to the next cluster boundary. A large value results in fewer 
file extensions over the life of a file; a small value results in numerous file 
extensions over the life of a file. When a file has numerous file extensions 
that may be noncontiguous, this slows record access. 


For file creation, if you do not specify a value or specify 0, VMS RMS uses 
the default specified by the DCL command SET RMS_DEFAULT/EXTEND_ 
QUANTITY. If this value is also 0, then VMS RMS uses the system default 
extension quantity specified by the SYSGEN parameter RMS_EXTEND_SIZE. 
If this value is 0, then VMS RMS computes the default value. 


When the value in this field, the value set by the SET RMS_DEFAULT 
/EXTEND_QUANTITY command, and the value of the SYSGEN parameter 
RMS_EXTEND_SIZE are all 0, VMS RMS calculates what is often a large 
value to minimize the number of extend operations that it must perform. At 
times, this value can exceed the available disk quota even though there is 
actually enough space for the file if only the required amount is used. You 
can use the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY to 
limit (explicitly specify) the extension size to the recommended number of 
blocks. An appropriate size is the number of blocks specified as the cluster 
size for the device (set by the DCL command INITIALIZE/CLUSTER_SIZE). 
For large files on a volume where there is sufficient disk space, consider using 
a multiple of the cluster size to improve subsequent performance. 
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When creating a new file, you can specify the extension quantity for the file 
by setting the desired value in the FABSW_DEQ field before or after issuing a 
Create service. This value becomes a permanent attribute for the file. 


When processing an existing file, you can temporarily override the default 
extension quantity specified when the file was created. To do this, set the 
desired value before or after issuing the Open service. Once the file is closed, 
the default extension quantity reverts to the value set when the file was 
created. 


See the discussion under FAB$B_BKS for indexed files. 


Note that the use of an allocation control XAB overrides the value in this 
field. See Chapter 8 for a detailed description of allocation control XABs. 





5.10 FABSL_DEV Field 


The device characteristics (DEV) field allows your program to obtain the 
generic characteristics of the device containing the file. You can locate and 
test the various bits in the field using symbolic offsets. This is a binary 
options field set by VMS RMS when you invoke an Open, Create, Display, or 
Parse service (this is set by the Parse service only if the NAM$V_SYNCHK 
option in the NAM$B_NOP field is clear). 


Table 5-2 describes the bits in the device characteristics field. Each bit 

has its own symbolic bit offset and mask value. These definitions are 

made available to your program by referring to the $DEVDEF macro in 
SYS$LIBRARY:STARLET.MLB. The symbolic bit offset is formed by prefixing 
the characteristic name with DEV$V_. The mask value is formed by prefixing 
the characteristic name with DEV$M_. For example, the DEV$V_REC bit has 
a mask value of DEV$M_REC. 


Table 5—2 Device Characteristics 


Bit Offset Description 

DEV$V_ALL Device is allocated. 

DEV$V_AVL Device is available for use. 

DEV$V_CCL Carriage control device. 

DEV$V_CDP Device has dual access paths, one of which is a remote node 
using an MSCP server. 

DEV$V_CLU Device is available on a VAXcluster. 

DEV$V_DET Terminal device is detached. 

DEV$V_DIR Directory-structured device. 

DEV$V_DMT ___ Device is marked for dismount. 

DEV$V_DUA Device has dual access paths, both of which use a disk class 
driver. 

DEV$V_ELG Device is error log enabled. 

DEV$V_FOD File-oriented device (disk and magnetic tape). 

DEV$V_FOR Device is mounted foreign (non-file-structured). 

DEV$V_GEN Device is a generic device. 
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Table 5—2 (Cont.) Device Characteristics 


Bit Offset 


DEV$V_IDV 
DEV$V_MBX 
DEV$V_MNT 
DEV$V_NET 
DEV$V_ODV 
DEV$V_OPR 
DEV$V_RCK 
DEV$V_RCT 
DEV$V_REC 


DEV$V_RND 
DEV$V_RTM 
DEV$V_RTT 
DEV$V_SDI 
DEV$V_SHR 
DEV$V_SPL 


_ DEV$V_SQD 


DEV$V_SWL 
DEV$V_TRM 
DEV$V_WCK 


Description 


Device can provide input. 

Device is a mailbox. 

Device is currently mounted. 

Network device. 

Device can accept output. 

Device has been enabled as an operator console terminal. 
Device has read-check enabled. 

Disk device is an RA80, RA81, RA82 or RA6O. 


Record-oriented device (terminal, mailbox, line printer, for 
example). If field is O, device is assumed to be block-oriented 
(disk device or magnetic tape device). All record-oriented 
devices are considered sequential in nature. 


Device is random access in nature (disk). 

Device is real-time in nature; not suitable for use by VMS RMS. ~ 
Terminal device is a remote terminal (DCL command SET HOST). 
Single directory device (master file directory only). 

Shareable device. 

Device is being spooled. 

Sequential block-oriented device (magnetic tape). 

Device is currently software write-locked. 

Terminal device. 


Device has write-check enabled. 


For DECnet operations, this field represents the actual characteristics of the 
target device when a Create, Open, or Display service is invoked. It is not 
filled in when a Parse service is invoked using a file specification that contains 


a node name. 





5.11 FAB$L_DNA Field 


The default file specification string address (DNA) field provides the address 
of a file specification string VMS RMS uses to apply defaults for any missing 
components of the file specification. This field works with the FAB$B_DNS 
field, which initializes the default file specification string size, to provide a 
default file specification string. Defaults are applied after VMS RMS examines 
the primary file specification string that the FAB$L_FNA field (described 
below) points to. : 


This field and the FAB$B_DNS field correspond to the FDL attribute FILE 
DEFAULT_NAME. 


The FAB$L_DNA field contains the symbolic address of a default file 
specification string, which is an ASCII string containing one or more 
components of a file specification. The components in the string must be 
in the order in which they would occur in a complete file specification. 
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The default file specification string is used primarily when a process accepts 
file specifications interactively; normally, file specifications known to a user 
program are specified completely in the FAB$L_FNA and FAB$B_FNS fields. 
You can specify defaults for one or more of the following file specification 


components: 
e Node 
e §=©Device 


¢ Directory 
e =6File name 
e File type 


e File version number 


The default file specification string is used only if components are missing 
from the string whose address is stored in the FAB$L_FNA field and those 
components are present in the default file specification string. 


If you use VAX MACRO, you can use the DNM keyword to specify the 
FAB$L_DNA and FAB$B_DNS fields. 





FABSB_DNS Field 


The default file specification string size (DNS) field indicates the size, in bytes, 
of the string whose address is contained in the FAB$L_DNA field. This field 
contains a numeric value in the range 1 to 255. 


This field and the FAB$L_DNA field correspond to the FDL attribute FILE 
DEFAULT_NAME. 





FAB$B_FAC Field 


The file access (FAC) field specifies the operations and services a process is 
seeking to use in accessing a file. RMS uses this field, together with the share 
field (SHR) in each potential accessor’s FAB, to determine whether or not 

to permit a process to access a file. The FAC field corresponds to the FDL 
primary attribute ACCESS. 


Within the FAC field, each bit position corresponds to an operation or service 
option that the process intends to use when accessing the file. In this manner, 
a process may specify several options, assuming they are compatible, by 
setting the appropriate bits. Each option has its own symbolic bit offset and 
mask value. For example, the GET service option has a symbolic bit offset of 
FAB$V_GET and a mask value of FAB${M_GET. 


When RMS attempts to open a file for a process, it examines the process’s 
FAB$B_FAC field to determine what operations or services the process is 
seeking to use in conjunction with the file access. 


VMS RMS determines whether or not the process seeking access to the file 
intends to use operations and services that are compatible with the sharing 
options permitted by processes currently accessing the file. It checks the FAC 
field of the requesting process to determine whether it requires read or write 
access to the file. It then checks the SHR field of the requesting process to 
determine whether it will share read or write access with other processes that 
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are accessing the file. A read (GET) implies read access. Delete (DEL), write 
(PUT), truncate (TRN), and update (UPD) all imply write access. 


For example, assume that Process A opens the file for GET access (FAC=GET) 
and is willing to share the file with processes that are doing GET and PUT 
accesses (SHR=GET,PUT). Since this is the only process accessing the file, 
RMS permits it to read access the file. 


Assume that a second process, Process B, wants to access the same file doing 
PUT accesses (FAC=PUT) and is willing to share the file with processes 
doing GET accesses and PUT accesses (SHR=GET,PUT). Because Process B is 
compatible with Process A (they both agree to share the file with any process 
that is doing either GET accesses or PUT accesses), VMS RMS permits the 
second process to access the file. 


Now assume that a third process, Process C, wants GET access (FAC=GET) to 
the same file but will share the file only with processes doing GET accesses 
(SHR=GET). Although Process C is compatible with Process A (FAC=GET), it 
is not compatible with Process B (FAC=PUT), so RMS denies Process C access 
to the file. Conversely, if C tries to access the file before B, C gets access and 
B is denied access. 


VMS RMS always grants file access to the first process accessing a file, 
assuming no security access restrictions exist. When a process acquires access 
to a file, RMS rejects any attempt to use a service not included in the initial 
access request. 


The FAB$B_FAC field options are listed below. 


Options 


FAB$V_BIO 

Requests file access for doing block I/O operations that use Read (FAB$V_ 
GET), Write (FAB$V_PUT) or the Space services. Specifying block I/O 
prohibits the use of record I/O operations (such as the Get, Put, Update, 
Delete, or Truncate services). 


This option corresponds to the FDL attribute ACCESS BLOCK_IO. 


FABS$V_BRO 

Requests file access for doing either block I/O or record I/O as determined 
by the state of the RAB$V_BIO bit in the RAB at connect time. For additional 
information, see Section 4.8, under the discussion of block I/O, and 

Section 7.19. 


This option corresponds to the FDL attribute ACCESS RECORD_IO. 
FABS$V_DEL 


Requests file access for invoking the Delete service (or the equivalent VAX 
language statement that deletes a record). This option applies only to relative 
and indexed files. 


This option corresponds to the FDL attribute ACCESS DELETE. 


FABSV_GET | 

Requests file access for invoking either the Get or Find service (or equivalent 
VAX language statement that reads a record). This is the default if a process 
requests access to a file without including FAB$B_FAC field information or if 
the FAB$V_DEL, FAB$V_UPD, or FAB$V_TRN option is set in the FAB$B_ 
SHR field. If the process takes the FAB$V_GET option together with either 


File Access Block (FAB) 
5.13 FAB$B_FAC Field 


the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Read 
service. 


This option corresponds to the FDL attribute ACCESS GET. 


FABSV_PUT 


Requests file access for invoking either the Put or Extend service (or the 
equivalent VAX language statement that writes a record or extends a file). 
This is the default when a process creates a file. If the process takes the 
FAB$V_PUT option together with either the FAB$V_BIO option or the 
FAB$V_BRO option, it can invoke the Write service. 


This option corresponds to the FDL attribute ACCESS PUT. 


FABSV_TRN 

Requests file access for invoking the Truncate service (or the equivalent VAX 
language statement that truncates a file). Also allows use of the RAB$L_ROP 
truncate-on-put (RAB$V_TPT) option with the Put and Write service. This 
option applies only to sequential files. 


This option corresponds to the FDL attribute ACCESS TRUNCATE. 


FAB$V_UPD 

Requests file access for invoking either an Update or Extend service (or the 
equivalent VAX language statement that rewrites a-reeord or extends a file). 
Also allows use of the RAB$L_ROP update-if (RAB$V_UIF) option for the 
Put service. 


This option corresponds to the FDL attribute ACCESS UPDATE. 





5.14 FABSL_FNA Field 


The file specification string address (FNA) field works with the FAB$B_FNS 
field to specify the primary file specification of the file to be processed. If this 
string does not contain all the components of a full file specification, VAX 
RMS uses the defaults supplied in the default file specification string (see 
FAB$L_DNA and FAB$B_DNS). If no default string is present or if the file 
specification is still incomplete, VMS RMS provides additional defaults. 


This field contains the symbolic address of a file specification string, which 
is an ASCII string containing one or more components of a file specification. 
This field is used as input by many file-processing services. To obtain the file 
specification returned by VMS RMS after it translates any logical names and 
applies defaults, a NAM block must be present (see FAB$L_NAM). 


If you use VAX MACRO, you can use the FNM keyword to specify the 
FAB$L_FNA and FAB$B_FNS fields. 


This field and the FAB$B_FNS field correspond to the FDL attribute FILE 
NAME. 
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FAB$SB_FNS Field 


The file specification string size (FNS) field specifies the size, in bytes, of the 
ASCII file specification string, whose address is contained in the FAB$L_FNA 
field. This field contains a numeric value in the range of 0 through 255. 


This field and the FAB$L_FNA field correspond to the FDL attribute FILE 
NAME. 


FABS$L_FOP Field 
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FAB$L_FOP is the symbolic offset value for the FAB’s file-processing options 
(FOP) field. This field specifies which of the various optional file operations 
are to be implemented for the process. 


The FOP is a 32-bit field in which each file-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple 
bits can be set), when applicable. Each option has a unique symbolic offset 
value and mask value but you need only specify the appropriate 3-letter 
mnemonic when coding a function. For example, the spool-file-on-close 
option has a symbolic offset value of FAB$V_SPL but to specify the option, 
you use the following MACRO statement: 


FOP=SPL 


As detailed in the appropriate descriptions, the only file-processing option 
bits that may be affected by VMS RMS services are the FAB$V_CBT, FAB$V_ 
CTG, FAB$V_RCK, and FAB$V_WCK bits. 


This section presents the file-processing options alphabetically within the 
various functional categories, of which there are seven: 


e Allocation and extension options 
e¢ Performance options 

¢ Reliability options 

e File name parsing modifiers 

e File disposition options 

e Magnetic tape processing options 


¢ Nonstandard processing options 


Table 5-3 lists each of the options alphabetically by category. 


Table 5-3 File Processing Options 
Option Symbolic Offset 


Allocation and Extension Options 


Contiguous best try FAB$V_CBT 
Contiguous allocation FAB$V_CTG 
Truncate at end of file FAB$V_TEF 
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Table 5—3 (Cont.) File Processing Options 


Option 


Performance Options 


Symbolic Offset 


Asynchronous operation FABS$V_ASY 
Deferred write FABSV_DFW 
Sequential only FAB$V_SQO 


Synchronous status 


Reliability Options 


FAB$SV_SYNCSTS 


Read-check FABSV_RCK 
Write-check FABSV_WCK 
File Name Parsing Modifier Options 

Create-if FAB$V_CIF 
Maximum version number FAB$SV_MXV 
Use NAM block inputs FABSV_NAM 
Output file parse FAB$V_OFP 
Supersede existing file FAB$V_SUP 
File Disposition Options 

Delete on close FABSV_DLT 
Submit command file on close FAB$V_SCF 
Spool file on close FAB$V_SPL 
Temporary marked for delete FABSV_TMD 
Temporary file FAB$SV_TMP 
Magnetic Tape Options 

Do not set to EOF FABS$V_NEF 
Current position FAB$V_POS 
Rewind file on close FABSV_RWC 
Rewind file on open FABSV_RWO 
Nonstandard Options 

Non-file-structured FABSV_NFS 
User file open FAB$V_UFO 


This field corresponds to the FDL primary attribute FILE. 
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Allocation and Extension Options 


FAB$V_CBT 


Contiguous best try; indicates that the file is to be allocated contiguously 

on a “best effort” basis. It is input to the Create service and output from 

the Open service to indicate the file status. Note that the FAB$V_CBT bit 
remains set only if allocation using one, two, or three extents is actually 
performed. That is, the FAB$V_CBT bit is switched off before the return from 
the Create service unless VMS RMS can allocate the file within three extents. 
The FAB$V_CBT option overrides the FAB$V_CTG option. Note that this 
option is ignored if multiple areas are defined for an indexed file. 


This option corresponds to the FDL attribute FILE BEST_TRY_ 
CONTIGUOUS. 


FABSV_CTG | 

Contiguous; indicates that the space for the file is to be allocated contiguously. 
If this cannot be done, the operation fails. It is input to the Create service 
and is output by the Open service to indicate the status of the file. Note that 
this option is ignored if multiple areas are defined for an indexed file. The 
FAB$V_CBT option overrides the FAB$V_CTG option. 


This option corresponds to the FDL attribute FILE CONTIGUOUS. 


FABSV_TEF 

Truncate at end of file; indicates that unused space allocated to a file is to be 
deallocated on a Close service. The FAB$V_TEF option applies to unshared 
sequential files. 


This option corresponds to the FDL attribute FILE TRUNCATE_ON_CLOSE. 


Performance Options 


FAB$V_ASY 


Asynchronous; indicates that the specified task is to be done asynchronously. 
The FAB$V_ASY option is relevant only to tasks that involve I/O operations 
and is ignored for process permanent files. The asynchronous I/O option is 
typically used with success/error ASTs, or in conjunction with the $WAIT 
service, to synchronize the program with task completion. When you specify 
FAB$V_ASY, you pass the address of the FAB as an argument to the AST 
routine and VMS RMS returns control to your program immediately. 


FAB$V_DFW 

Deferred write; indicates that writing back to the file of modified I/O buffers 
is to be deferred until the buffer must be used for other purposes. This option 
applies to relative files, indexed files and sequential files opened for shared 
access. 


This option corresponds to the FDL attribute FILE DEFERRED_WRITE and is 
not supported for DECnet operations. 


FAB$V_SQO 


Sequential only; indicates that the file can be processed only in a sequential 
manner, permitting certain processing optimizations. Any attempt to perform 
random access results in an error. The FAB$V_SQO option is input to the 
Create and Open services. 


Note: 
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This option corresponds to the FDL attribute FILE SEQUENTIAL—ONLY. 


For DECnet operations, this option enables file transfer mode for Get, Put, 
Read, and Write services. File transfer mode is a Data Access Protocol 
(DAP) feature that allows several records to be transferred in a single- 
network I/O operation to maximize throughput for single-direction, 
sequential access file transfer. 


FAB$V_SYNCSTS 

When you select this option, VMS RMS returns the success status RMS$_ 
SYNCH if the requested service completes its task immediatly. The most 
common reason for not completing a task immediatly is that the task involves 
I/O operations. 


The status RMS$_SYNCH is returned in RO. Refer to the FAB$L_STS field 
for the actual success status or failure status of the task. 


The FAB$V_SYNCSTS option is best used in conjunction with the FAB$V_ 
ASY option. 


Reliability Options 


FABSV_RCK 


Read-check; specifies that transfers from disk volumes are to be checked by a 
read-compare operation, which effectively doubles the amount of disk I/O at 
some increase in reliability. This option is an input to the Open and Create 
services. If FAB$V_RCK is set, then checking is performed for the duration 
of the access. The FAB$V_RCK option is also an output of the Open service, 
which indicates the default for the file. This option is not available for RX01 
and RX02 devices, or for any device that has been mounted using the DCL 
command MOUNT/FOREIGN. 


This option corresponds to the FDL attribute FILE READ_CHECK. 


FAB$V_WCK 

Write-check; indicates that transfers to disk volumes are to be checked by a 
read-compare operation. The FAB$V_WCK option is similar to the FAB$V_ 
RCK option. This option is not available for RX01 and RX02 devices, or 
for any device that has been mounted using the DCL command MOUNT 
/FOREIGN. 


This option corresponds to the FDL attribute FILE WRITE_CHECK. 


File Name Parsing Modifiers 


FABSV_CIF 

Create if nonexistent; opens an already existing file if it exists. If the file does 
not exist, it is created and the alternate success status RMS$_.CREATED is 
returned to indicate that the file was created, not just opened. The FAB$V_ 
CIF option is input only to the Create service and overrides the FAB$V_SUP 
option. When the create-if option is used with a search list logical name and 
the file is not found in any of the file specifications supplied using the search 
list, the file is created using the file specification from the first element of the 
search list. 


This option corresponds to the FDL attribute FILE CREATE_IF. 
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FABSV_MXV 


Maximize version number; indicates that the version number of the file 
should be the maximum of the explicit version number given in the file 
specification, or one greater than the highest version number for an existing 
file in the same directory with the same file name and file type. This option 
enables you to create a file with a specific version number (if the requested 
version number is greater than that of the existing file) or a file with a version 
number that is one higher than the existing file’s version number. 


This option is used as input to the Create service only and it corresponds to 
the FDL attribute FILE MAXIMIZE_VERSION (default is “YES”). 


FABSV_NAM 

Use NAM block inputs; indicates that the NAM block whose address is 
contained in the FAB$L_NAM (name block address) field provides the 
device, file, and/or the directory identification when a file is being opened, 
closed, or erased (deleted). If a file is being created, the field specifies the 
device and directory identification. 


This option has no corresponding FDL attribute and it is not supported for 
DECnet operations. See Chapter 6. 


FABS$V_OFP 


Output file parse; specifies that related file resultant file specification strings, if 
used, are to provide directory, file name, and file type defaults only (requires 
NAM block). 


This option corresponds to the FDL attribute FILE OUTPUT_FILE_PARSE. 


FABS$V_SUP 
Supersede existing file; allows an existing file to be superseded on a Create 


service by a new file of the same name, type, and version. The FAB$V_CIF 
and the FAB$V_MXV option take precedence over the FAB$V_SUP option. 


This option corresponds to the FDL attribute FILE SUPERSEDE. 


File Disposition Options 


FAB$V_DLT 


Delete file on Close; indicates that the file is to be deleted when closed. This 
option may be specified for the Create, Open, or Close services. However, 
if you set the bit when you create or open a file, VMS RMS deletes the file 
when you close it, regardless of the state of the bit when you invoke the 
Close service. You can specify the FAB$V_DLT option with the FAB$V_SCF 
or FAB$V_SPL option. 


This option corresponds to the FDL attribute FILE DELETE_ON_—CLOSE. 


FABSV_SCF 

Submit command file on Close; indicates that the file is to be submitted as a 
batch-command file to the process-default batch queue (SYS$BATCH) when 
the file is closed. This option can be specified for the Create, Open, and Close 
services. However, if you set the bit when you create or open a file, VMS 
RMS submits the file to SYS$BATCH when you close it, regardless of the 
state of the bit when you invoke the Close service. 


The FAB$V_SCF option applies to sequential files only and it corresponds to 
the FDL attribute FILE SUBMIT_ON_CLOSE. 
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FAB$V_SPL 

Spool file on Close; indicates that the file is to be spooled to the process- 
default print queue (SYS$PRINT) when the file is closed. This option can 
be specified for the Create, Open, or Close services. However, if you set the 
bit when you create or open a file, VMS RMS spools the file to SYS$PRINT 
when you close it, regardless of the state of the bit when you invoke the 
Close service. 


The FAB$V_SPL option applies to sequential files only and it corresponds to 
the FDL attribute FILE PRINT_ON_CLOSE. 


FABSV_TMD 
Temporary file marked for delete; indicates that a temporary file is to be 
created but is to be deleted when the file is closed. This option is input only 


to the Create service. The FAB$V_TMD option takes precedence over the 
FAB$V_TMP option. 


This option corresponds to the FDL attribute FILE TEMPORARY. 


FAB$V_TMP 

Temporary file; indicates that a temporary file is to be created and retained, 
but that no directory entry is to be made for it. This option is used solely as 
input to the Create service. If you have a NAM block, you are given the file 
identification (FID) of the file which you can use to reopen the file. If you 
do not have a NAM block or if you do not save the FID, the file becomes 
inaccessible once it is closed. The FAB$V_TMD option overrides the FAB$V_ 
TMP option. 


This option corresponds to the FDL attribute FILE DIRECTORY_ENTRY 
(“NO’ means this bit is set). 


Magnetic Tape Processing Options 


FABSV_NEF 


Do not position to end of file; inhibits positioning to the end of a file when 
a tape file is opened and the FAB$B_FAC (file access) field indicates a Put 
service. 


This option corresponds to the FDL attribute FILE MT_NOT_EOF. 


FAB$V_POS 

Current position; directs VMS RMS to position the magnetic tape volume set 
immediately after the most recently closed file when it creates the next file. 
If you use this option when you invoke the $CREATE service, VMS RMS 
overwrites all files located beyond the current tape position. 


The FAB$V_POS option corresponds to the FDL attribute FILE MT_ 
CURRENT_POSITION. The FAB$V_RWO option overrides the FAB$V_ 
POS option. 


FAB$V_RWC 


Rewind file on Close; specifies that the magnetic tape volume is to be 
rewound when the file is closed. This option can be specified for the Close, 
Create, or Open services. 


This option corresponds to the FDL attribute FILE MT_CLOSE_REWIND. 
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FAB$V_RWO 

Rewind on Open; specifies that the magnetic tape volume is to be rewound 
before the file is opened or created. If you use this option when you invoke 
the $CREATE service, VMS RMS overwrites all files currently on the tape 
volume or volume set. The FAB$V_RWO option takes precedence over the 
FAB$V_POS option. 


This option corresponds to the FDL attribute FILE MT_OPEN—_REWIND. 


Nonstandard Processing Options 
FABSV_NFS 


Non-file-structured; indicates (on an Open or Create service) that the volume 
is to be processed in a non-file-structured manner. This option allows the use 
of volumes created on non-DIGITAL systems. 


The FAB$V_NFS option corresponds to the FDL attribute FILE NON_—FILE— 
STRUCTURED and it is not supported for DECnet operations. 


FABS$V_UFO 

User file open; indicates that VMS RMS operations for this file are limited to 
opening it or creating it. To perform additional processing of the file, invoke 
the SYS$QIO system service using the channel number returned by VMS 
RMS in the status value field (FAB$L_STV). This channel is assigned the 
access mode of the caller unless otherwise specified by the FAB$V_CHAN_— 
MODE bits. 


If you specify this option, you must set the FAB$B_SHR field FAB$V_UPI 
bit option unless the file is not shared (FAB$B_SHR field FAB$V_NIL option 
is set). For the Create service, the end-of-file mark is set to the end of the 
block specified in the FAB$L_ALQ field on input. For either the Open or 
Create services, the FAB$W_IFI field is set to 0 on return to indicate that VMS 
RMS cannot perform any more operations on the file. If you set the FAB$V_ 
UFO option with the Open or Create service, the channel needs only to be 
deassigned when you finish with the file. A Close service is not required. 


This option corresponds to the FDL attribute FILE USER_FILE_OPEN and it 
is not supported for DECnet operations. 





5.17 FABS$B_FSZ Field 
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The fixed-length control area size (FSZ) field is used only for variable with 
fixed-length control (VFC) records. When you create a file with this record 
type, you must set the value for the fixed-control area before you issue the 
Create service. When you open an existing file that contains variable with 
fixed control records, VMS RMS sets this field equal to the value specified 
when the file was created. The FAB$B_FSZ field is not applicable to indexed 
files. 


This field corresponds to the FDL attribute FILE CONTROL —FIELD_SIZE. 


This field contains a numeric value in the range of 1 to 255 that indicates, in 
bytes, the size of the fixed control area; the default size is two bytes. If you 
do not specify a value or specify 0, then the default size is used. 
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5.18 FABS$W_GBC Field 


The global buffer count (GBC) field indicates the requested number of global 
buffers for a file. This field contains a numeric value in the range of 0 to 
32,767; the default is 0. 


Global buffers support sharing of I/O buffers by more than one process. 
The use of global buffers can minimize I/O operations for a shared file, thus 
reducing record access time at the cost of using additional system resources. 
VMS RMS is able to locate requested records (or blocks) in the global buffers 
associated with this file, which it can read directly from memory, eliminating 
much I/O. However, since global buffers use global sections, the value 
contained in FABSW_GBC is limited by systemwide restrictions on resources 
determined by the system parameters GBLSECTIONS (number of global 
sections), GBLPAGES (number of global page table entries), GBLPAGFIL 
(number of systemwide pages allowed for global page-file sections, or scratch 
global sections), and RMS_GBLBUFQUO (total number of simultaneously 
active VMS RMS global buffers allowed for the system). 


For a complete description of these parameters, see the VMS System Generation 
Utility Manual. 


If global buffers are specified for a file, global buffers are used instead of local 
(process) buffers, with the exception of deferred write operations (FAB$L— 
FOP field FAB$V_DFW option). 


The value that is specified when the file is created is returned in the FABSW_ 
GBC field as output from the Open service. This value is then used as input 
to the Connect service. 


If you want to override the default value specified when the file was created, 
you can set a different value in the FAB$W_GBC field after opening the file 
but before invoking the Connect service. If you do not want to use global 
buffers, you can clear the field before issuing the Connect service if the 
default value is not 0. 


If you modify the value in the FABSW_GBC field that is returned from the 
Open service prior to the Connect service, this action determines whether or 
not global buffers are assigned to your process. 


If you want to permanently change the default global buffer count value for 
the file, use the following DCL command: 


$ SET FILE file-spec /GLOBAL_BUFFERS=buffer-count 


If you want to permanently clear the default global buffer count for a file, use 
the following DCL command: 


$ SET FILE file-spec /GLOBAL_BUFFERS=0 


You can also vary the number of global buffers used each time you process 
the file. If you choose this method, you change (or clear) the FABSW_GBC 
field after you open the file, but before you invoke the Connect service. In 
this case, the specified value is assigned to the FABSW_GBC field, or the 
FAB$W_GBC field remains clear only for the current processing of the file; 
that is, you do not permanently alter the FAB$W_GBC field in the FAB. If 
no value is specified in the FABSW_GBC field when the file is created, the 
default value is 0. 
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The number of global buffers for a file is determined by the first record stream 
to connect to the file (systemwide). If the file is already open and connected, 
then the number of global buffers is already set and modifications made 
before the Connect service are useful only to request that this process use (or 
not use) global buffers. 


To specify a read-only global buffer cache, the initial accessor must set the 
FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits on. Selecting the 
FAB$V_MSE option turns on locking to coordinate access to the global buffer 
cache, 


You can use global buffers for all file organizations opened for shared record 
access. If the global buffer count is nonzero for the first process that connects 
to the file, then a temporary global section that is large enough to contain the 
specified number of buffers (as well as internal VMS RMS data structures) is 
created and mapped. Subsequent processes that connect to the file map this 
section, thus allowing multiple processes to reference a single set of one or 
more buffers without performing additional I/O operations. Thus, the first 
user to open the file requesting global buffers determines the number of the 
global buffers. 


This field corresponds to the FDL attribute FILE GLOBAL_BUFFER_COUNT 
and it is not supported for DECnet operations. 





5.19 FABSW_IFI Field 


The internal file identifier (IFI) field is set by VMS RMS to associate the FAB 
with the corresponding internal file access block. VMS RMS sets this field 
on successful Create or Open services. It is then an input for subsequent 
Close, Connect, Display, and Extend services. The Close service deallocates 
the internal control structures and clears the FAB$W_IFI field. When the 
user file open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no 
internal structures are allocated on Create or Open services. Therefore, the 
FAB$W_IFI field remains cleared. 


There is no FDL equivalent for this field. 


5.20 FAB$V_LNM_MODE Subfield 
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The logical name translation access mode (LNM—MODE) subfield is the 
component part of the FAB$}B_ACMODES field that specifies the outermost 
access mode that VMS RMS uses to translate logical names during parsing. 
The FAB$V_LNM_—MODE subfield contains one of the following values: 


O None 

1 Executive mode (PSL$C_EXEC) 

2 Supervisor mode (PSL$C_SUPER) 
3 User mode (PSL$C_USER) 


The default value is 0 (none), which VMS RMS interprets as user mode. 


The FAB$V_LNM_MODE field is not supported for DECnet operations, and 
it is ignored during any DECnet remote file access. 


There is no corresponding FDL equivalent for this field. 
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5.21 FABSL_MRN Field 


The maximum record number (MRN) field applies only to relative files and 
indicates the highest record number that can be written to a file. 


This field contains a numeric value of the highest numbered record allowed 
in the file, in the range of 0 to 2,147,483,647, although the maximum value 
depends on the number of blocks on the device to be used. The default for 
this field is 0. 


If you attempt to write (put) or retrieve (get) a record with a relative record 
number higher than the specified limit, an error occurs and VMS RMS returns 
a message indicating an invalid record number. Checking is suppressed if you 
specify 0 for the FAB$6L_MRN field. 


Note that VMS RMS does not maintain the relative record number of the 
highest existing record in the file. 


This field corresponds to the FDL attribute FILE MAX_RECORD_NUMBER. 


5.22 FABSW_MRS Field 


The maximum record size (MRS) field defines the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size (minus overhead) for relative files. 


This field contains a numeric value in the range applicable to the file type 
and record format (see Table 5-4) that indicates the size of the records in the 
file, in bytes. This value specifies the number of bytes of data and does not 
include any control bytes associated with each record. 


For fixed-length records, the value represents the actual size of each record 
in the file. You must specify a size when you create a file with fixed-length 
records. 


For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size, except for the limitations listed in Table 5-4 and certain 
physical limitations. For magnetic tape files, a value of 0 sets an effective 
maximum record size that is equal to the block size minus 4. 


The size of variable-length records must conform to physical limitations. 
With indexed and relative files, for example, records may not cross bucket 
boundaries. If both the FAB$B_BKS and FAB$W_MRS fields are 0 (not 
specified) for an indexed file, VMS RMS attempts to calculate a reasonable 
bucket size, usually 2. Thus, if any record requires more than two buckets, 
you must explicitly specify the required value for the FAB$B_BKS or the 
FAB$W_MRS field. If FAB$B_BKS field is specified, the value should specify 
a bucket size large enough to exceed the longest possible record. 


For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 


For all relative files, the size is used in conjunction with the FAB$B_BKS field 
to determine the size of the record cell. You must specify the FAB$W_MRS 
field when you create a relative file. 
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You specify a value when you invoke a Create service. VMS RMS returns the 
maximum record size when you invoke an Open service. 


Table 5-4 summarizes the maximum record size allowed for the various file 
and record formats. 


Table 5-4 Maximum Record Size for File Organizations and Record 
Formats 


File Organization 


Record Format 


Maximum 
Record Size 


Sequential Fixed length 32,767 
Sequential (disk) Variable length 32,765 
Sequential (disk) VFC 32,767-FSZ' 
Sequential (disk) Stream 32,767 
Sequential (disk) Stream-CR 32,767 
Sequential (disk) Stream-LF 32,767 
Sequential (ANSI Tape) Variable length 9,995 
Sequential (ANSI Tape) VFC 9,995-FSZ' 
Relative Fixed length 32,255 
Relative Variable length 32,253 
Relative VFC 32,253-FSZ' 
Indexed, Prolog 1 or 2 Fixed length 32,234 
Indexed, Prolog 1 or 2 Variable length 32,232 
Indexed, Prolog 3 Fixed length 32,224 
Indexed, Prolog 3 Variable length 32,224 


'The FSZ represents the size, in bytes, of the fixed control area in a record having VFC 
record format. On a disk device, the length of the largest record in a sequential file using 
variable or VFC format is also maintained by VMS RMS and is available through the longest 
record length field (XAB$W-_LRL) in the file header characteristics XAB (XABFHC). See 
Chapter 10. 


For DECnet remote file access, the maximum record size may be set by the 
/NETWORK_BLOCK_COUNT=n qualifier to the SET RMS_DEFAULT 
command or by a $XABITM parameter. DECnet remote file access can 
support record sizes as large as the record sizes that VMS RMS supports. The 
default number of blocks is equal to the SYSGEN parameter RMS_DFNBC, 
the default for which is 8 blocks (4096 bytes). For more information about the 
SET RMS_DEFAULT command, see the VMS DCL Dictionary. The SYSGEN 
parameters are detailed in the VMS System Generation Utility Manual. 


This field corresponds to the FDL attribute RECORD SIZE. 
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5.23 FABSL_NAM Field 


The name block address (NAM) field specifies the address of the NAM 
block used to invoke a file service, such as an Open or Create. The NAM 
block, described in Chapter 6, is required only in conjunction with the file 
specification processing services. But it can also be used with other services, 
typically to obtain a file specification string after all logical name translation 
is completed and all defaults applied. Note that the FAB$L_FOP option 
FAB$V_NAM must be specified for the NAM block to be used as input (see 
FAB$L_FOP). 





5.24 FABSB_ORG Field 


The file organization (ORG) field assigns the organization of the file. 


The FAB$B_ORG field is a keyword value field in which each file 
organization has a symbolic value. Options are identified using 3-letter 
mnemonics. Each option in the FAB$B_ORG field has its own symbolic 
constant value. For example, the relative (REL) file organization has a 
constant value of FAB$C_REL. . 


You must set this field before you invoke a Create service. VMS RMS returns 
the contents of this field when you invoke an Open service. The options are 
described in the following list: 


e FAB$C_IDX — Indexed file organization 
e FAB$C_REL — Relative file organization 
e FAB$C_SEQ — Sequential file organization (default) 


This field corresponds to the FDL attribute FILE ORGANIZATION. 





5.25 FAB$B_RAT Field 


The record attributes (RAT) field indicates the record control information 
associated with each record in a file. 


Within the FABSB_RAT field, each record attribute has a corresponding bit 
assignment. Each record attribute option in the field has a unique symbolic 
bit offset and constant value. For example, the CR record attribute has a 
symbolic bit offset of FAB$V_CR and a mask value of FABSM_CR. 


Only the FAB$V_BLK option can be paired with another option. You cannot 
use FAB$V_CR, FAB$V_FTN, and FAB$V_PRN together in any combination. 


For most VMS programs, the default value for this field is FAB$V_CR 
(carriage return). When you create your own file, however, the default 
value is 0. When you want to create a stream format file or any text file 

(a file containing ASCII text), specify the FAB$V_CR option for the Create 
service. VMS RMS sets this field when you invoke an Open service. When a 
process-permanent file is accessed indirectly for output, the value in this field 
is always an input value. VMS RMS automatically converts the records from 


the record attributes specified to the actual attributes of the process-permanent 
file. 


This field corresponds to the FDL primary attribute RECORD. 
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Options 


FAB$V_BLK 


Applicable to sequential files only; indicates that records are not permitted to 
cross block boundaries. 


This option corresponds to the FDL attribute RECORD BLOCK_SPAN. 


FAB$V_CR 


Indicates that each record is to be preceded by a line feed and followed by a 
carriage return when the record is written to a carriage control device such as 
a line printer or terminal. 


This option corresponds to the FDL attribute RECORD CARRIAGE_— 
CONTROL CARRIAGE_RETURN. 


FABSV_FTN 


Indicates that the first byte of each record contains a FORTRAN (ASA) 
carriage control character. 


This option corresponds to the FDL attribute RECORD CARRIAGE 
CONTROL FORTRAN. Records are defined as follows: 


Byte O ASCII 

Value (hex) Character Meaning 

O (null) Null carriage control (sequence: print buffer 
contents). 

20 (space) Single-space carriage control (sequence: line 
feed, print buffer contents, carriage return). 

30 0 Double-space carriage control (sequence: line 
feed, line feed, print buffer contents, carriage 
return). 

31 1 Page eject carriage control (sequence: form 
feed, print buffer contents, carriage return). 

28 + Overprint carriage control (sequence: print 
buffer contents, carriage return). Allows 
double printing for emphasis. 

24 $ Prompt carriage control (sequence: line feed, 
print buffer contents). 

Other values Same as ASCIil space character: single-space 
Carriage control. 

FAB$V_PRN 


Indicates print file format for variable with 2-byte fixed-length control records, 
where the fixed control area contains the carriage control specification. The 
first byte of the fixed control area constitutes a “prefix” area, and the second 
byte constitutes a “suffix” area, specifying carriage control to be performed 
before and after printing the record respectively. 
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This option corresponds to the FDL attribute RECORD CARRIAGE 
CONTROL PRINT. 


The coding scheme of both bytes is presented below (even though they are 
interpreted separately): 


Bit 7 Bits 6—O Meaning 


6) 0) No carriage control is specified, that is, NULL. 


O 1-7F Bits 6 through O are a count of new lines (line feed 
followed by carriage return). 


Bit 7 Bit 6 Bit 5 Bits 4—0 Meaning 


1 0) 0 0-1F Output the single ASCII control 
character specified by the 
configuration of bits 4 through O 
(7-bit character set). 


1 1 O 0-1F Output the single ASCII control 
character specified by the 
configuration of bits 4 through O 
that are translated as ASCII characters 
128 through 159 (8-bit character set). 


1 1 1 0-1F Reserved. 





5.26 FABSB_RFM Field 


The record format (RFM) field specifies the format for all the records in a file. 


The FAB$B_RFM field is a keyword value field where each record format has 
a symbolic value. Options are identified by mnemonics. Each option has its 
own symbolic constant value. For example, the FIX (fixed) record format has 
a symbolic constant value of FAB$C_FIX; the STMCR (stream with carriage 
return) record format has a symbolic constant value of FAB6C_STMCR. 


When you create the file, you must set this field before you invoke the Create 
service. VMS RMS returns the record format when you invoke an Open 
service. The record format options are described below. 


This field corresponds to the FDL attribute RECORD FORMAT. 


Options 


FABSC_FIX 
Indicates fixed-length record format. 


This option corresponds to the FDL attribute RECORD FORMAT FIXED. 


FAB$C_STM 


Indicates stream record format. Records are delimited by FF, VT, LF, or CR 
LF. This format is supported for sequential files only. 


This option corresponds to the FDL attribute RECORD FORMAT STREAM. 
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FAB$C_STMCR 


Indicates stream record format. Records are delimited by CR. This format is 
supported for sequential files only. 


This option corresponds to the FDL attribute RECORD FORMAT STREAM _ 
CR. 


FABSC_STMLF 


Indicates stream record format. Records are delimited by LF. This format is 
supported for sequential files only. 


This option corresponds to the FDL attribute RECORD FORMAT STREAM 
LF. 


FAB$C_UDF 


Indicates undefined record format. The undefined record format is valid for 
sequential files only. This is the default value if the FAB is not initialized 
with a $FAB macro. 


This option corresponds to the FDL attribute RECORD FORMAT 
UNDEFINED. 


FABSC_VAR 


Indicates variable-length record format. For the $FAB macro, this is the 
default value. 


This option corresponds to the FDL attribute RECORD FORMAT VARIABLE. 


FABS$C_VFC 


Indicates variable-length with fixed-length control record format. This format 
is not supported for indexed files. 


This option corresponds to the FDL attribute RECORD FORMAT VFC. 


If you intend to use stream record format, then specify the FAB$V_CR record 
attribute (see FAB$B_RAT). 





5.27 FABS$B_RTV Field 
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The retrieval window size (RTV) field specifies the number of retrieval 
pointers VMS RMS is to maintain in memory for the file. Retrieval pointers 
are stored in the file header and indicate the beginning of each extent 
associated with the file. If a file has been extended repeatedly, the extents 
may be scattered noncontiguously on the disk, requiring numerous retrieval 
pointers. When VMS RMS needs to access a new extent, it must first obtain 
the retrieval pointer for that extent. VMS RMS first looks for the retrieval 
pointer in the retrieval window, which contains the number of retrieval 
pointers specified by this field. If the retrieval pointer is not in the retrieval 
window, VMS RMS must first read the file header, causing an additional I/O 
operation. 


This field contains a numeric value in the range of 0 through 127, or 255. A 
value of 0 indicates that VMS RMS is to use the system default number of 
retrieval pointers. A value of 255 means to map the entire file, if possible. If 
you specify a value of 255 when creating a file, the initial number of retrieval 
pointers is minimal; as records are added, however, the number of retrieval 
pointers increases as the number of extents increases. The system resources 
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required for retrieval windows are subtracted from the buffered I/O quota of 
the process. Values from 128 to 254 (inclusive) are reserved for future use. 


This field corresponds to the FDL attribute FILE WINDOW_SIZE and it is not 
supported for DECnet operations. 





5.28 FABS$L_SDC Field 


The secondary device characteristics (SDC) field is equivalent to the 
FAB$L_DEV field, except that secondary device characteristics refer to 

the intermediate device used for spooling or the logical link for DECnet 
operations. Within the FAB$L_SDC field, the bit definitions are the same as 
those defined for the FAB$L_DEV field (see Table 5-2). Like the FAB$L_ 
DEV field, the bit definitions must first be made available to your process 
referring to the $DEVDEF system macro definition; the values are set by 
certain VMS RMS services (see FAB$L_—DEV for additional information). 





5.29 FABSB_SHR Field 


The file sharing (SHR) field defines the record operations that the opening 
process allows sharing processes to perform. VMS RMS supports file sharing 
for all file organizations. 


Within the FABS$B_SHR field, each record operation that sharing processes 
are permitted to do has a corresponding bit assignment. You can specify 
multiple record operations (multiple bits may be set). 


Options are identified by symbolic bit offsets. Note that conflicts between the 
names of symbolic offsets in the FAB$B_SHR field and the names of symbolic 
offsets in the FAB$B_FAC field are resolved by prefixing the letters SHR to 
the symbolic offset in the FAB$B_SHR field. For example, both the FAB$B_ 
FAC and FAB$B_SHR fields have a bit that specifies the get record option. In 
the FAB$B_FAC field, this bit offset is assigned the symbol FAB$V_GET; in 
the FAB$B_SHR field, this bit is assigned the symbol FAB$V_SHRGET. 


Note that the letters SHR in the mnemonic part of the bit offset symbol 
may be omitted by VAX MACRO programs. Thus, the GET option, which 
is common to the FAB$B_FAC and FAB$B_SHR fields, has a symbolic 

bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but 
VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_ 
GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_ 
SHRDEL, and FAB$V_SHRUPD options. 


The way in which VMS RMS uses the file access (FAB$B_FAC) field and file 
sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC 
field discussion. 


Note that if you do not specify a value, VMS RMS enters a value of 0 in the 
FAB$B_SHR field. Defaults apply as follows: 


e If the FAB$B_FAC field is set or defaulted to FAB$V_GET, the FAB$B_ 
SHR field defaults to FAB6V_SHRGET. 


e §6If the FAB$B_FAC field is set or defaulted to either FAB$V_PUT, FAB$V_ 
DEL, FAB$V_UPD, or FAB$V_TRN, the FAB$B_SHR field defaults to 
FAB$V_NIL. Thus, write-sharing must be explicitly requested using the 
FAB$B_SHR field (because it is not the default). 
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See the Guide to VMS File Applications for additional details on file sharing. 
This field corresponds to the FDL primary attribute SHARING. 


The following list includes descriptions of the sharing options. 


Options 
FAB$V_MSE 


Allows multistream access and is relevant for record operations only. You 
must specify FAB$V_MSE whenever you want to call Connect services for 
multiple RABs for this FAB. 


Note that if you specify the FAB$V_MSE and FAB$V_BIO options, you must 
set the FAB$V_UPI bit regardless of the other sharing bits. To specify a read- 
only global buffer cache, the initial accessor must set the FAB$B_SHR field 
FAB$V_SHRGET and FAB$V_MSE bits. Selecting the FAB$V_MSE option 
turns on locking to coordinate access to buffers. 


The FAB$V_MSE option is not supported for DECnet operations; an error is 
returned. Although VMS RMS cannot perform multistreaming for DECnet 
operations, you can obtain similar functionality by using multiple FABs to 
access the file in a shared manner. 


This option is available for all file organizations and corresponds to the FDL 
attribute SHARING MULTISTREAM. 


FABSV_NIL 


Prohibits any file sharing by other users. If FAB$V_NIL is specified with 
other options, it takes precedence. 


This option corresponds to the FDL attribute SHARING PROHIBIT. 


FABSV_SHRPUT 
Allows other users to write records to the file or to extend the file. 


This option corresponds to the FDL attribute SHARING PUT. 


FAB$V_SHRGET 
Allows other users to read the file. 


This option corresponds to the FDL attribute SHARING GET. 


FAB$V_SHRDEL 
Allows other users to delete records from the file. 


This option corresponds to the FDL attribute SHARING DELETE. 
FAB$V_SHRUPD 


Allows other users to update records that currently exist in the file or extend 
the file. 


This option corresponds to the FDL attribute SHARING UPDATE. 


FABS$V_UPI 


This option is used when the user wants to assume responsibility for 
interlocking of multiple, simultaneous accessors of a VMS RMS file. This 
option disables all VMS RMS locking for the current access of the file. Except 
for block I/O, the FAB$V_MSE option overrides the FAB$V_UPI option. 
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Usually, the FAB$V_UPI option is used for a file that is open for block I/O 
(FAB$V_BIO or FAB$V_BRO). 


When you select the FAB$V_UFO option, you must also select the FAB$V_ 

UPI option if the file is write shared. A file is specified as being write shared 
when you select either the FAB$V_PUT option, the FAB$V_DEL option, the 
FAB$V_TRN option or the FAB$V_UPD option in the FAB$B_SHR field. 


This option corresponds to the FDL attribute SHARING USER_INTERLOCK. 





FABS$L_STS Field 


VMS RMS sets the completion status code (STS) field with success or failure 
codes before it returns control to your program (except for a subset of 
errors, as detailed in Section 2.4). Register 0 contains the same status as 
the STS field. Potential error codes for specific services are listed under their 
descriptions in Part III. Status codes are discussed further in Part I. 


FAB$L_STV Field 


The status value (STV) field is set by VMS RMS and, on the basis of the 
operation performed and the contents of the completion status code (FAB$L — 
STS) field, communicates additional completion information to your program. 
See Part III for the instances when VMS RMS uses the status value field. 





FABSL_XAB Field 


The extended attribute block address (XAB) field specifies the XAB, or first of 
a series of XABs, that you want to use for file operations. This field contains 
the symbolic address of an XAB control block. A value of 0 (the default) 
indicates no XABs for the file. 


For some operations, you must associate extended attribute blocks (XABs) 
with a FAB to convey additional attributes about a file. (See Part I for a 
description of an XAB.) The FAB$L_XAB field can contain the symbolic 
address of the first associated block (of a potential chained list of such blocks) 
for the file. 


VMS RMS uses XAB values as follows: 


1 If you specify an XAB for either an Open or Display service, VMS RMS 
returns the file attributes to the XAB. 


2 If you specify an XAB for a Create, Close, or Extend service, VMS RMS 
uses the XAB as input to those functions. 
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The name (NAM) block provides additional fields for extended file 
specification use, including parsing and obtaining the actual file specification 
used for a file operation. 





Summary of Fields 


The symbolic offset, size, and a brief description of each NAM block field are 
presented in Table 6-1. Additional details are given in the remaining sections 


of this chapter. 


Table 6—1 NAM Block Fields 


Field Offset 


NAM$B_ BID" 
NAM$B_BLN' 
NAM$B_DEV? 
NAMS$L_DEV? 
NAM$W_DID? 
NAM$B_DIR? 
NAM$L_DIR? 
NAM$T_DVI? 
NAM$L_ESA 
NAM$B_ESL? 
NAM$B_ESS 
NAM$W__FID? 
NAM$L_FNB? 


NAM$B_NAME?2 
NAMS$L_NAME? 


NAM$B_NODE? 
NAM$L_NODE? 
NAM$B_NOP 
NAMS$L_RLF 
NAM$L_RSA 
NAM$B_RSL? 
NAM$B_RSS 


Size 
(Bytes) 


1 
1 
1 
4 
6 
1 
4 
1 
4 
1 
1 
6 
4 
1 
4 
1 
4 
1 
4 
4 
1 
1 


Description 


Block identifier 

Block length 

Device string length 

Device string address 
Directory identification 
Directory string length 
Directory string address 
Device identification 
Expanded string area address 
Expanded string length 
Expanded string area size 
File identification 

File name status bits 

File name string length 

File name string address 
Node name string length 
Node name string address 
Name block options 

Related file NAM block address 
Resultant string area address 
Resultant string length 


Resultant string area size 


'This field is statically initialized by the $NAM macro to identify this control block as a 


NAM. 


2This field cannot be initialized by the $NAM macro. 


Name Block (NAM) 
6.1 Summary of Fields 


Table 6—1 (Cont.) NAM Block Fields 


Size 
Field Offset (Bytes) Description 
NAM$B_TYPE? 1 File type string length 
NAMS$L _TYPE? 4 File type string address 
NAM$B_VER? 1 File version string length 
NAM$L_VER? 4 File version string address 
NAMS$L_WCC? 4 Wildcard context 


2This field cannot be initialized by the $NAM macro. 


Each NAM block field is described below. The NAM block fields have no 
corresponding FDL equivalents. However, if your application requires the 
presence of a NAM block, consider using the $NAM macro (or equivalent) 
perhaps in a USEROPEN or a USERACTION routine. 


Unless indicated otherwise, each field is supported for DECnet operations 
when the remote node is a VMS system. Note that the words “DECnet 
operations” in the following descriptions refer to remote file operations 
between two VMS systems. For information about the support of VMS RMS 
options for remote file access to other systems, see the VMS Networking 


~ Manual. 


Depending on the VMS RMS services to be used, the user may need to 
allocate program storage for the expanded string and the resultant string. 
The Parse service uses the expanded string to pass information related to 
wildcards (or search lists) to the Search service. When it creates a resultant 
string for other VMS RMS file services, VMS RMS uses the expanded string 
as a work area to apply defaults. You can use the resultant string with 
VMS RMS file services to provide the file specification that results from the 
translation of logical names and the application of defaults. Typical uses of 
the resultant string include showing the resulting file specification after a 
partial file specification is entered by a terminal user, for error reporting, and 
for logging the progress of a program. 


To request use of the expanded or resultant strings, you must indicate to VMS 
RMS the address and size of the user-allocated buffer to receive the string. 
The expanded string is indicated by the NAM$L_ESA and NAM$B_ESS 
fields; the resultant string is indicated by the NAM$L_RSA and NAM$B_ 
RSS fields. When it fills in the expanded or resultant strings, VMS RMS 
returns the actual length of the returned string in the NAM$B_ESL or 
NAM$B_RSL fields. 


The format and arguments of the $NAM and $NAM_STORE macros are 
defined in Appendix B. 
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6.2 File Specification Component Descriptors 





File Specification Component Descriptors 


For each element of the fully qualified file specification returned in the 
expanded-string field or the resultant-string field in the NAM block, VMS 
RMS returns a descriptor in the NAM block. Two fields describe the element: 
a 1-byte size field and a 4-byte (longword) address field. The fields of these 
descriptors are described as one of the following: 


NAMS$B_xxx (size field of xxx) 
NAMS$L _xxx (address field of xxx) 


Each descriptor is summarized below. 


Descriptor 
NAM$B_NODE, NAM$L_NODE 


. Node name descriptor, including access control string and double colon (::) 


delimiter. 


NAM$B_DEV, NAMSL_DEV 
Device name descriptor, including colon (:) delimiter. 


NAMS$B_DIR, NAMSL_DIR 
Directory name descriptor, including brackets ([ and ] or < and > ). 


NAMS$B_NAME, NAMSL_NAME 


File name descriptor or, if the file specification following a node name is 
within quotation marks (“file”), a quoted string descriptor. 


NAMS$B_TYPE, NAM$L_TYPE 
File type descriptor, including period (.) delimiter. 


NAM$B_VER, NAMS$L_VER 


File version number descriptor, including semicolon (;) or period (.) 
delimiter. 


These descriptors are returned, enabling the program to extract a particular 
component from the resultant string without having to parse the resultant 

or expanded string. The entire resultant or expanded string, including 
delimiters, is described by the various component descriptors. If the value in 
the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L— 
RSA field. If the value in the NAM$B_RSL field is 0 and the value in the 
NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA 
field. In all other cases, they are undefined. 
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6.4 


6.5 


6.6 


Name Block (NAM) 


6.2 File Specification Component Descriptors 


As an example, a resultant file specification and its file specification 
component descriptors are shown below. 


NODE‘TEST password”::WORK_DISK:[TEST.TEMP]FILE.DAT;3 


NODE NODE"“TEST password”: 
DEV WORK_DISK: 

DIR [TEST.TEMP] 

NAME FILE 

TYPE .DAT 

VER 3 


You can use the field descriptors individually or collectively to describe 
sections of the resultant or expanded string. For example, if you want to use 
the file name and file type fields, use NAM$L_NAME for the starting address 
and NAM$B_NAME+NAM$B_TYPE for the total length. 





NAMS$B_BID Field 


The block identifier (BID) field is a static field that identifies this control block 
as a NAM block. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
NAM$C_BID (this is done by the $NAM macro). 


NAMS$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
NAM block, in bytes. Once set, this field must not be altered unless the 
control block is no longer needed. This field must be initialized to the 
symbolic value NAM$C_BLN (this is done by the $NAM macro). 


NAM$B_DEV and NAM$L_DEV Fields 


The device name length and address (DEV) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 





NAM$W_DID Field 


co?) 


The directory identification (DID) field identifies the directory for the file. 
VMS RMS outputs this 3-word field as part of the Open, Create, Display, and 
Parse services. If, once you open the file, you want to refer to this directory 
again, you can do so more quickly by specifying that the NAM block has a 
valid directory identifier. 


This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 
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NAM$B_DIR and NAMS$L_DIR Fields 


The directory name length and address (DIR) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAMS$B_RSL fields, which contain the length of the returned file specification 
string. 





NAMS$T_DVI Field 


The device identification (DVI) field defines the device for the file. VMS RMS 
outputs this field as part of the Open, Create, Display, and Parse services. 
You can use this field with the file identification field to reopen the file by 
referring to the NAM block. The symbolic value NAM$S_DVI gives the 
length of this field in bytes. The form of this field is a counted string. The 
first byte is a count of the number of characters following it. 


This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 





NAMS$L_ESA Field 


The expanded string area address (ESA) field contains the symbolic address of 
a user buffer in the application program to receive the file specification string 
resulting from the translation of logical names and the application of default 
file specification information. 


You must specify this field for processing wildcard characters. 





NAMS$B_ESL Field 


The expanded string length (ESL) field is set by VMS RMS as part of the 
Open, Create, and Parse services. This field contains the length, in bytes, 
of the file specification string returned in the buffer whose address is in the 
NAM$L_ESA field. 





NAMS$B_ESS Field 


The expanded string area size (ESS) field contains the size of the user- 
allocated buffer whose address is contained in the NAM$L_ESA field. 


This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the file specification string, in the range of 0 through 
290: 


The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of an expanded file specification string. 
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NAM$W_FID Field 


The file identification (FID) field is a 3-word field that VMS RMS uses to 
identify the file when it invokes an Open, Create, or Display service. When 
you want to open a file by using the file identifier, set this field before you 
open the file. 


This field is not supported for DECnet operations; it is ignored on input and 
zero-filled on output. 





NAMS$L_FNB Field 
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The file name status (FNB) field is a binary options field that VMS RMS 
uses to convey status information obtained from the file specification parsing 
routine. Each bit within this field denotes a specific status relative to the 
various components of the file specification. 


Each status bit has its own offset and mask value. For instance, the number of 
directory levels (DIR—LVLS) field has a symbolic bit offset of NAM$V_DIR— 
LVLS and a mask value of NAM$M_DIR_LVLS. The bits and the conditions 
they express for the NAM$L_FNB field are described in Table 6-2. 


Table 6—2 NAMS$L_FNB Status Bits 


Field Offset 


NAM$V_CNCL_DEV 
NAM$V_DIR_LVLS 


NAM$V_EXP_DEV 
NAM$V_EXP_DIR 
NAM$V_EXP_NAME 
NAM$V_EXP_TYPE 
NAM$V_EXP_VER 
NAM$V_GRP_MBR 


NAM$V_HIGHVER 


NAM$V_LOWVER 


NAM$V_NODE 
NAM$V_PPF 
NAM$V_QUOTED 


Description 


Device name is a concealed device. 


Indicates the number of subdirectory levels (value is O 
if there is a user file directory only); a 3-bit field. 


Device name is explicit. 
Directory specification is explicit. 
File name is explicit. 

File type is explicit. 

Version number is explicit. 


Directory specification is in the group/member number 
format. 


A higher-numbered version of the file exists (output 
from Create and Enter services). For DECnet 
operations, this bit is returned as a binary zero. 


A lower-numbered version of the file exists (output 
from Create and Enter services). For DECnet 
operations, this bit is returned as a binary zero. 


File specification includes a node name. 
File is indirectly accessed process-permanent file. 


File specification includes a quoted string; indicates 
that the file name length and address field contains 
a quoted string file specification. Applies to network 
operations or magnetic tape devices only.' 


1To distinguish network quoted string file specifications from quoted strings containing 
ASCII “a” file names (supported for ANSI-labeled magnetic tapes), both the NAM$V__ 
QUOTED and NAM$V_NODE bits are set. 
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6.13 NAMS$L_FNB Field 


Table 6—2 (Cont.) NAM$L_FNB Status Bits 
Field Offset Description 


NAM$V_ROOT_DIR Device name incorporates a root directory. 


NAM$V_SEARCH_LIST A search list logical name is present in the file 
specification. 


NAM$V_WILDCARD File specification string includes a wildcard; returned 
whenever any of the other wildcard bits is set. 


NAM$V_WILD_DIR Directory specification includes a wildcard character. 
NAM$V_WILD_GRP Group number contains a wildcard character. 
NAM$V_WILD_MBR Member number contains a wildcard character. 
NAM$V_WILD_NAME File name contains a wildcard character. 


NAM$V_WILD_SFD1-— = Subdirectory 1 through 7 specification includes a 
NAM$V_WILD_SFD7 wildcard character. 


NAM$V_WILD_TYPE File type contains a wildcard character. 


NAM$V_WILD_UFD User file directory specification includes a wildcard 
character. 
NAM$V_WILD_VER Version number contains a wildcard character. 


NAM$B_NAME and NAM$L_NAME Fields 


The file name length and address (NAME) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 


NAM$B_NODE and NAM$L_NODE Fields 


The node name length and address (NODE) field contains a pointer to either 
the NAM$L_ESA or NAM$L_RSA fields, depending on whether Parse 
service was invoked or an Open, Create, or Search service was invoked. 

You can tell which name string is used by referring to the NAM$B_ESL or 
NAM$B_RSL fields, which contain the length of the returned file specification 
string. 





NAM$B_NOP Field 


The name block options (NOP) field indicates the options applicable to the 
file name parsing services. 
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6.16 NAM$B_NOP Field 


The NAM$B_NOP field is a binary options field in which each option has 

a corresponding bit assignment. Multiple options can be specified (multiple 
bits can be set) but the default state for each bit is clear (not set). Each option 
has its own symbolic bit offset and mask value. For example, the SYNCHK 
option has a symbolic bit offset of NAM$V_SYNCHK and a mask value of 
NAM$M_SYNCHK. 


Each of these options is discussed below. 


Options 


NAMS$V_NOCONCEAL 


When used with the Open, Create, Search, or Display services, a concealed 
device logical name, if present, is translated into its physical device name (and 
directory, if so defined) in the resultant string field, whose address is supplied 
by the NAM$L_RSA field. If this option is not set and a concealed device 
name is used, the concealed device name appears in the resultant string field, 
instead of the physical device name (and directory, if so defined). 


NAM$v_PWD 


When used with the Create, Open, Parse, Search, or Display services, the 
password in the access control string of a node specification, if present, is 
returned unaltered in the expanded or resultant file specification fields. If 
you do not select this option, the actual password used is replaced by the 
word “password” in the resultant or expanded file specification string fields 
for security reasons. 


NAM$V_SRCHXABS 

When used with the Search service for remote file access, this option directs 
VMS RMS to fill in the FAB and any chained XABs as if a Display service had 
been invoked. This allows you to obtain file attribute information using the 
Search service without the need to open the file. 


NAM$V_SYNCHK 


This gives you the option of using the Parse service to verify the syntax 
validity of the file specification without invoking I/O processing that verifies 
the actual existence of the specified device, directory and file. 


If you invoke the Parse service without setting this bit, an accompanying I/O 
process verifies that the device and directory exist. Note that this processing 
does not verify the existence of the file; you can only verify the existence of 
the file with either a $SEARCH or $OPEN. 


If you opt to set the NAM$V_SYNCHK bit when you invoke the Parse 
service, VMS RMS does not return the device characteristics (FAB$L__DEV 
and FAB$L_SDC fields) and does not fill in the NAM$W_DID and NAM$T_ 
DVI fields, rendering the results of the $PARSE unusable for subsequent 
Search services. 





6.17 NAMS$L_RLF Field 


The related file NAM block address (RLF) field contains the symbolic address _ 
of the NAM block for the related file. This field supports the secondary file 
concept of the command language (DCL), giving an extra default level in 
processing file specifications. 


Name Block (NAM) 
6.17 NAMS$L_RLF Field 


To provide an extra level of file specification defaults, the related NAM block 
must have been used previously by an Open, Create, Search or Display 
service to create a resultant file specification string. Moving the address of 
the related NAM block into the NAM$L_RLF field of the current NAM block 
specifies that the previously parsed NAM block’s resultant file specification 
string should be used as a default when the current NAM block is parsed. 
Note that the previously parsed NAM block must contain a resultant file 
specification (see NAM$L_RSA and NAM$B_RSS for additional details). 


Refer to the Guide to VMS File Applications for additional details on file 
specification parsing concepts. 





6.18 NAMS$L_RSA Field 


The resultant string area address (RSA) field contains the symbolic address 
of a buffer in your program to receive the resultant file specification string. 
The NAM$B_RSS field must also be specified to obtain a resultant file 
specification string. 


This string is the fully specified name of the file that results from the 
resolution of all system defaults, including version numbers and wildcard 
character substitution in the expanded file name string. You must specify this 
field for wildcard processing. 


6.19 NAMS$B_RSL Field 


The resultant string length (RSL) contains the length, in bytes, of the 
resultant file specification string returned in the buffer whose address is 
in the NAM$L_RSA field. 


6.20 NAMS$B_RSS Field 


The resultant string area size (RSS) field defines the size of the user-allocated 
buffer whose address is contained in the NAM$L_RSA field. 





This field contains a numeric value representing the size, in bytes, of the user 
buffer that will receive the resultant file specification string, in the range of 0 
through 255. 


The symbolic value NAM$C_MAXRSS defines the maximum possible length 
of a resultant file specification string. 


6.21 NAM$B_TYPE and NAM$L_TYPE Fields 


The file type length and address (TYPE) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can tell 
which name string is used by referring to the NAM$B_ESL or NAM$B_RSL 
fields, which contain the length of the returned file specification string. 
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6.22 NAM$B_VER and NAMSL_VER Fields 


NAM$B_VER and NAMS$L_VER Fields 


The file version length and address (VER) field contains a pointer to either the 
NAM$L_ESA or NAM$L_RSA fields, depending on whether a Parse service 
was invoked or an Open, Create, or Search service was invoked. You can 
determine the name string that is used by referring to the NAM$B_ESL or 
NAMS$B_RSL fields, which contain the length of the returned file specification 
string. 





NAM$L_WCC Field 


The wildcard context (WCC) field contains the information needed to use 
wildcard characters in place of the various file specification components. In 
particular, this field restarts a directory search to find the next matching file 
name, type, and/or version number. You can also use it to identify various 
VMS RMS extended contexts; for instance, during remote file processing. 


6-10 


7.1 


Record Access Block (RAB) 


The record access block (RAB) defines run-time options for a record stream 
and for individual operations within a predefined record stream context. After 
you connect the file to a record stream and associate the record stream with 
a FAB, you use the RAB fields to specify the next record you want to access 
and to identify appropriate record characteristics. 





Summary of Fields 


Table 7-1 


Field Offset 


RAB$B_BID' 
RAB$L_BKT 
RAB$B_BLN' 
RABSL_CTX 
RAB$L_FAB 
RAB$W_ISI? 
RABS$L_KBF 
RAB$B_KRF 
RAB$B_KSZ 
RAB$B_MBC 
RAB$B_MBF 
RAB$L_PBF 
RAB$B_PSZ 
RAB$B_RAC 
RABS$L_RBF 
RABSW_RFA 
RAB$L_RHB 
RAB$L_ROP 
RAB$W_RSZ 
RAB$L_STS? 
RAB$L_STV? 


Table 7-1 gives the symbolic offset, size, FDL equivalent, and a brief 
description of each RAB field. 


RAB Fields 


Size 
(Bytes) 


ff PH FP HKO FH - FH ase He KH KY HF FH LH = 


FDL Equivalent 


None 

CONNECT BUCKET_CODE 

None 

CONNECT CONTEXT 

None 

None 

None 

CONNECT KEY_OF_REFERENCE 
None 

CONNECT MULTIBLOCK_COUNT 
CONNECT MULTIBUFFER_COUNT 
None 

None 

CONNECT? 

None 

None 

None 

CONNECT? 

None 

None 


None 


Description 


Block identifier 

Bucket code 

Block length 

User context 

File access block address 
Internal stream identifier 
Key buffer address 

Key of reference 

Key size 

Muitiblock count 
Multibuffer count 
Prompt buffer address 
Prompt buffer size 
Record access mode 
Record buffer address 
Record file address 
Record header buffer 
Record-processing options 
Record size 

Completion status code 
Status value 


This field is statically initialized by the $RAB macro to identify this control block as a RAB. 


2This field cannot be initialized by the $RAB macro. 


3This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 7—1 (Cont.) RAB Fields 


Field Offset es FDL Equivalent Description 
RAB$W_STVO4 2 None Low-order word status value 
RABSW_STV24 2 None High-order word status value 
RAB$B_TMO 1 CONNECT TIMEOUT_PERIOD Timeout period 

RAB$L __UBF 4 None User record buffer address 
RAB$W_USZ 2 None User record buffer size 
RAB$L_XAB 4 None Next XAB address 


4 Alternate definition of RAB$L_STV field. 


Each RAB field is described below. Unless indicated otherwise, each field is 
supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $RAB macro and the $RAB_STORE macro 
are described in Appendix B. 





RAB$B_BID Field 


The block identifier (BID) field is a static field that identifies the block as a 
RAB. Once set, this field must not be altered unless the control block is no 
longer needed. This field must be initialized to the symbolic offset value (this 
is done by the $RAB macro). 





RAB$L_BKT Field 


The bucket code (BKT) field is used with records in a relative file and when 
performing block I/O. 


This field contains a relative record number or a numeric value representing 
the virtual block number to be accessed. 


For relative files, the relative record number of the record acted upon (or 
which produced an error) is returned to the RAB$L_BKT field only after the 
completion of a sequential operation. That is, VMS RMS returns the relative 
record number when you set the record access mode for sequential access 
(RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service. 


Before performing block I/O on disk devices, this field must contain the 
virtual block number (VBN) of the first block you want to read or write. 

For all other devices, this field is not used. If you specify a VBN of 0, VMS 
RMS begins the block transfer at the block pointed to by the next block 
pointer (NBP). (The NBP is an internal pointer maintained by VMS RMS; it is 
described in Section 4.8.) 
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7.3 RAB$L_BKT Field 


This field is also input to the Space service to specify the number of blocks to 
be spaced forward or backward. 


This field corresponds to the FDL attribute CONNECT BUCKET_CODE. 





RAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
RAB, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
RAB$C_BLN (this is done by the $RAB macro). 


RABSL_CTX Field 


The user context (CTX) field contains any user-selected value, up to four bytes 
long. This field is devoted exclusively to your use. VMS RMS makes no use 
of the contents of this field; therefore, you can set any value you want in this 
field. For example, you could use this field to communicate with a completion 
routine in your program. 


This field corresponds to the FDL attribute CONNECT CONTEXT. 


RABSL_FAB Field 


The file access block address (FAB) field contains the symbolic address of the 
FAB for the file. Before you invoke the Connect service, you must set this 
field to indicate the address of the FAB associated with the open file. 


RAB$W_ISI Field 


The internal stream identifier (ISI) field associates the RAB with a 
corresponding FAB. VMS RMS sets this field after the execution of a Connect 
service. A Disconnect service clears this field. This field should not be altered. 


RABS$L_KBF Field 


The key buffer address (KBF) field contains the symbolic address of the buffer 
containing the key for random access. Note that the RAB$B_KBF field has the 
same Offset as the RAB$B_PBF (prompt buffer address) field, but no conflict 
is presented because the fields are used in mutually exclusive operations. 


You use this field when the RAB$B_RAC (record access mode) field specifies 
random access by key value and you set it to the address of the buffer that 
contains the key of the desired record. For a relative file (or for a sequential 
disk file with fixed-length records), the key is the relative record number. 
For an indexed file, the key is the key value within the record for the key of 
reference (RAB$B_KRF). 


Record Access Block (RAB) 
7.8 RABSL_KBF Field 


Before you invoke the Get or Find service in random mode to an indexed file, 
you place the address of a location containing a key value in the RAB$L_ 
KBF field. The size of this key value must be specified in the RABS$B_KSZ 
field. During execution of the Get or Find service, VMS RMS uses the key 
value described by the RAB$L_KBF and RAB$B_KSZ fields to search an 
index (which you specify through the contents of the RAB$B_KRF) and locate 
the desired record in the file. The type of match (that is, exact, generic, 
approximate, or approximate and generic) that VMS RMS attempts between 
the key value you specify and key values in records of the file is determined 
by the RAB$B_KSZ field and the RAB$L_ROP field. 





7.9 RABS$B_KRF Field 


The key of reference (KRF) field specifies the key or index (primary, first 
alternate, and so on) to which the operation applies. The RAB$B_KRF field is 
applicable to indexed files only. 


This field contains a numeric value representing the key path to records in a 
file. The value 0, the default, indicates the primary key. The values 1 through 
254 indicate alternate keys. 


When your program invokes a Get or Find service in random access mode, 
the key of reference specifies the index to search for a match on the key value 
that is described by the RAB$L_KBF and RAB$B_KSZ fields. When your 
program invokes a Connect or Rewind service, the key of reference identifies 
the index in the file of the next record in the stream. The next record is 
important when records are retrieved sequentially. 


This field corresponds to the FDL attribute CONNECT KEY_OF_ 
REFERENCE. 





7.10 RABS$B_KSZ Field 


The key size (KSZ) field contains a numeric value equal to the size, in bytes, 
of the record key pointed to by the RAB$L_KBF field. 


Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ 
(prompt buffer size) field but no conflict is presented because the fields are 
used in mutually exclusive operations. 


For indexed files, the size of the key depends on the key data type: 


e For string keys, a value from 1 through the size of the key field can be 
used. If the specified size is less than the size of the key field, then only 
the leftmost characters of each key are used for comparison. 


e For numeric key data types, a value of 0 causes VMS RMS to use the key 
data type defined at file creation to determine the key size. A nonzero 
value is checked against the defined size, and an error is returned if they 
are not equal. 


Note that for DECnet operations, the RAB$B_KSZ field must be explicitly 
specified as a nonzero value because the key data type information may not 
be available to VMS RMS at the local node. 
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The size of the relative record number of a record in a relative file or a 
sequential file with fixed-length records is a longword, positive, integer value; 
therefore, the key size is 4. For relative record numbers, the default value 

of 0 causes a key size of 4 to be used. For DECnet operations, however, the 
RAB$B_KSZ field must be explicitly specified as 4 for relative files. 


With indexed files, the size of key values in bytes of an indexed file can be 
from 1 to 255 bytes. 


A program may access indexed file records directly in one of four ways: 
e By an exact match 

e¢ By an approximate match 

e By a generic match 


¢ By a combination of approximate and generic matches 


The program specifies the type of match using the RAB$B_KSZ field together 
with two bits from the RAB$L_ROP field: the RAB$V_KGE (logically 
synonymous with RAB$V_EQNXT) bit and the RAB$V_KGT (logically 
synonymous with RAB$V_NXT) bit. 


¢ To specify an exact match, set a value in the RAB$B_KSZ field equal to 
the number of bytes in the key, and reset the RAB$V_KGE bit and the 
RAB$V_KGT bit. 


¢ To specify an approximate match, set a value in the RAB$B_KSZ field 

equal to the number of bytes in the key, and set the appropriate bit. 
Specifically, if you want to match on a record having either an equal 
key value or the next value (greater for ascending sort order, lesser for 
descending sort order) set the RAB$V_KGE (logically synonymous with 
RAB$V_EQNXT) bit. If you want to match on a record having the next 
value and to ignore equal key values, set the RAB$V_KGT (logically 
synonymous with RAB$V_NxXT) bit. 


Note: Sort order is established in the data type (XAB$B_DTP) field of the 
associated XABKEY when the file is created. 


¢ To specify a generic match, set a value in the RAB$B_KSZ field equal to 
the number of leading bytes in the key you want to match on, and set the 
RAB$V_KGE bit and the RAB$V_KGT bit. 


¢ To specify an approximate generic match, set a value in the RAB$B_KSZ 
field equal to the number of leading bytes in the key you want to match 
on, and set the appropriate bit. 





7.11 RABS$B_MBC Field 


The multiblock count (MBC) field applies only to sequential disk file 
operations. This field specifies the number of blocks, in the range of 0 
through 127, to be allocated to each I/O buffer and correspondingly, the 
number of blocks of data to be transferred in each I/O unit. If this field is 
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not specified or is specified as 0, the process default for the multiblock count 
is used. If the process default is also 0, VMS RMS uses the system default. 
If the system default is also 0, then the default size for each I/O buffer is 

1 block. The DCL command SET RMS_DEFAULT is used to set process or 
system defaults. 


When it invokes the Connect service, VMS RMS uses the RAB$B_MBC field 
to determine the number of blocks in the I/O transfers for this record stream 
and allocates a buffer with the appropriate storage capacity. Note that the 
RAB$B_MBF (multibuffer count) field may be used to allocate multiple buffers 
of this size for the record stream. 


The use of the RABSB_MBC field optimizes data throughput for sequential 
operations, and does not affect the structure of the file. It reduces the number 
of disk accesses for record operations, resulting in faster program execution. 
However, the extra buffering increases memory requirements. 


Note that the RAB$B_MBC field is not used with block I/O. With 
multiblocks, the number of blocks in an I/O unit is fixed by the multiblock 
count, whereas in block I/O operations the number of blocks being 
transferred is specified by the program. 


This field corresponds to the FDL attribute CONNECT MULTIBLOCK— 
COUNT and it is not supported for DECnet operations. 
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The multibuffer count (MBF) field indicates the number of process-local I/O 
buffers you want VMS RMS to allocate when you invoke the Connect service 
for a record stream. 


This field contains a numeric value in the range of 0 to 127 that represents 
the number of buffers to be allocated. 


If this field is not specified or is set to 0, VMS RMS uses the process default 
for the particular file organization and device type. If the process default is 
also 0, the system default for the particular file organization and device type 
applies. If the system default is likewise 0, one buffer is allocated. However, 
if read-ahead or write-behind is specified, a minimum of two buffers is 
allocated. A minimum of two buffers is also allocated for an indexed file. 


VMS RMS requires that at least one buffer allocated for sequential and relative 
files and at least two buffers for indexed files, unless the file is to be processed 
with block I/O operations only. Multiple buffers can be used efficiently to 
overlap I/O time with compute time, particularly in read-ahead or write- 
behind processing (see RAB$L_—_ROP for information on these options), and 
to increase use of the buffers (as compared to disk I/O) when performing 
random processing. 


Note that the RABSB_MBF field is not used when block I/O access is 
specified with the Open, Create, or Connect services because no buffers 
are required. 


This field corresponds to the FDL attribute CONNECT MULTIBUFFER— 
COUNT and it is not supported for DECnet operations. 
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7.13 RAB$L_PBF Field 


The prompt buffer address (PBF) field points to a character string to be used 

as a prompt for terminal input. Note that the RAB$B_PBF field has the same 
offset as the RAB$B_KBF (key buffer address) field but because the fields are 
used in mutually exclusive operations, no conflict is presented. 


This field contains the symbolic address of the buffer containing the prompt 
character string. If you select the RAB$V_PMT option of the RAB$L_ROP 
field when you invoke a Get service, VMS RMS outputs this character string 
to the terminal before the Get service begins its task. 


To perform any carriage control on the terminal, you must insert the 
appropriate carriage control characters into this character string. 


This field is not supported for DECnet operations; it is ignored. 


7.14 RABS$B_PSZ Field 


The prompt buffer size (PSZ) field indicates the size of the prompt character 
string to be used as a terminal prompt. This field contains the size, in bytes, 
in the range of 0 to 255. 


Note that the RAB$B_PSZ field has the same offset as the RAB$B_KSZ (key 
buffer size) field but no conflict is presented because the fields are used in 
mutually exclusive operations. 


This field is not supported for DECnet operations; it is ignored. 


7.15 RABS$B_RAC Field 


The record access mode (RAC) field indicates the method of retrieving or 
inserting records in the file; that is, whether records are read (or written) 
sequentially, directly, or by record file address. Only one access method may 
be specified for any single record operation, but you can change the record 
access mode between record operations. 


The RAB$B_RAC field is a keyword value field in which each record access 
mode has a symbolic offset. Options are identified using mnemonics. Each 
access mode in the RAB$B_RAC field has its own symbolic constant. For 
example, the SEQ (sequential) access mode has the symbolic constant 
RAB$C_SEQ. 


The RAB$B_RAC field is not applicable to block I/O operations and there is 4 
no corresponding FDL attribute for this field. 


The record access mode options and their meanings are described below. 


Options 
RAB$C_SEQ 


Indicates sequential record access mode (the default); it can be specified with 
any type of file organization. 


Records read from (or written to) sequential files are accessed in chronological 
order. That is, older records are accessed before newer records. 
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Records read sequentially from indexed files are accessed by the key of 
reference according to the key’s sort order. Where records have duplicate 
keys, older records are read before newer records regardless of the key’s sort 
order. 


For example, assume an ascending key indexed file with four 2-byte records 
(Al, B1, B2, C1) where the key is the first byte of each record. When 
processed sequentially, the records are encountered in the following order: 


Al Bi B2 C1 


Here records B1 and B2 have the duplicate key B, but record B1 was inserted 
chronologically before record B2 and therefore, is encountered before B2 
when the program is reading records sequentially. 


If this file is reorganized as a descending-key indexed file, the records are 
encountered in the following order: 


Cl Bl B2 Al 


Note that the chronological order of insertion for the two records with 
duplicate keys is maintained without regard to sort order. 


When records are written sequentially to indexed files, VMS RMS verifies that 
the key value of each successive record is ordered correctly with respect to the 
key value in the previously written record. For example, with a descending 
key of reference VMS RMS ensures that the key value of the third record 
written is less than the value of the second record. 


RABSC_KEY 

Indicates random access by key. For relative files and sequential files on 
disk with fixed-length records, random access is by relative record number. 
Indexed files are accessed directly by specifying the appropriate value for the 
key of reference. 


RAB$C_RFA 


Indicates random access by record file address; used for all disk file 
organizations. 





7.16 RABS$L_RBF Field 


When a program invokes a service that writes records to a file, the output 
record buffer address (RBF) field contains the symbolic address of the buffer 
that holds the record to be written. 


When you invoke the Get or Read service, VMS RMS sets this field to the 
address of the record just read from the file; you need not initialize this field. 
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7.17 RABSW_RFA Field 


The record file address (RFA) field comprises three words that define the 
physical disk address (not symbolic address) of the current record. 


After the successful execution of a Get, Put, or Find service, VMS RMS sets 
the RAB§W_RFA field to the address of the record acted on by the operation. 
This address provides an unambiguous means of directly locating this same 
record at some later time but is meaningful for disk files only. 


You can store the contents of the RABSW_RFA field for future use. When 
you want to retrieve the record again, merely restore the saved contents of 
the field, set the record access mode to random by RFA, and invoke a Get or 
Find service. 


The following rules apply to RFA access: 


1 There are two additional names for portions of this field: RAB$L—RFAO 
is the offset of the first of three words; RAB$W_RFA4 is the offset of the 
last word. 


Using VAX MACRO, the field may be copied: 


MOVAL RABBLK,RO 
MOVL RAB$L_RFAO (RO) , SAVE_RFA 
MOVW RAB$W_RFA4 (RO) , SAVE_RFA+4 


2 RFA values remain valid for a record in a sequential file as long as the 
record is within the space defined by the logical file; that is, until the file 
is truncated to a point before the record. 


3 RFA values remain valid for a record in a relative file for the life of the 
file; that is, until the file is reorganized, using the VMS Convert Utility, or 
deleted. 


4 With an indexed file, RFA values remain valid until the file is reorganized, 
using the VMS Convert Utility, or deleted. Note that the VMS Convert 
/Reclaim Utility partially reorganizes a file while maintaining RFA values. 





7.18 RABSL_RHB Field 


The fixed-length record header buffer (RHB) field contains the symbolic 
address of the record header buffer, which VMS RMS uses only when 
processing VFC records. 


For a Get service, VMS RMS strips the fixed control area portion of the record 
and places it in the buffer whose address is specified in this field. For Put or 
Update services, VMS RMS writes the contents of the specified buffer to the 
file as the fixed control area portion of the record. 


If this field is not specified, VMS RMS assumes the absence of a record 
header buffer. When no record header buffer exists, the fixed control area is 
discarded for a Get service, zeroed for a Put service, and left unchanged for 
an Update service. 


The size of the fixed control area is defined in the FAB, using the FAB$B_FSZ 
field. You must ensure that the buffer size described in the RAB$L_—RHB field 
is equal to the value specified by the FAB$B_FSZ field. 


7-9 


7.19 


Record Access Block (RAB) 
7.19 RAB$L_ROP Field 





RAB$L_ROP Field 


RAB$L_ROP is the symbolic offset for the RAB’s record-processing options 
(ROP) field. This field specifies which of the various optional record 
operations are to be implemented for the program. 


The ROP is a 32-bit field in which each record-processing option has a 
corresponding bit assignment to let you specify multiple options (multiple 
bits can be set), when applicable. Each option has a unique symbolic offset 
and a unique mask value but you need only specify the appropriate 3-letter 
mnemonic when coding a function. For example, the end-of-file option is 
assigned symbolic offset RAB$V_EOF, but to specify the option, you use the 
following MACRO statement: 


ROP=EQOF 
The record-processing option bits are never affected by VMS RMS services. 


This section describes the record-processing options alphabetically by 
functional category, of which there are seven: 


¢ Connect service input options 
¢ Indexed file options 

¢ Miscellaneous options 

e Performance options 

e Put service options 

e Record locking options 


¢ Terminal device options 

This field corresponds to the FDL primary attribute CONNECT. 
Table 7-2 lists the options alphabetically by category. 

Table 7-2 Record Processing Options 

Option Symbolic Offset 


Connect Service Options 


Block |/O RAB$V_BIO 
End of file RAB$V_EOF 
Read ahead RAB$V_RAH 
Synchronous status RAB$V_SYSCSTS 


Write behind RAB$V_WBH 


Indexed File Options 


Key greater than or equal RAB$V_EQNXT (or RAB$V_KGE) 


Limit RAB$V_LIM 
Load RAB$V_LOA 
Key greater than RAB$V_NXT or (RAB$V_KGT) 
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Table 7—2 (Cont.) Record Processing Options 


Option 


Miscellaneous Option 


Timeout RAB$V_TMO 
Performance Options 

Asynchronous RAB$V_ASY 
Fast delete RAB$V_FDL 
Locate mode RAB$V_LOC 
Read ahead RAB$V_RAH 
Write behind RAB$V_WBH 
Put Service Options 

Truncate on put RAB$V_TPT 
Update-if RAB$V_UIF 
Record Locking Options 

Do not lock RAB$V_NLK 
Nonexistent record RAB$SV_NXR 
Lock for read RAB$V_REA 
Lock for write RAB$V_RLK 
Ignore read lock RAB$V_RRL 
Timeout RAB$V_TMO 
Manual unlock RAB$V_ULK 
Wait to lock RAB$SV_WAT 
Terminal Device Options 

Cancel CTRL/O RAB$V_CCO 
Convert RAB$V_CVT 
Extended operation RAB$V_ETO 
Prompt RAB$V_PMT 
Purge type-ahead RAB$V_PTA 
Read, no echo RAB$V_RNE 
Read, no filter RAB$V_RNF 
Timeout RAB$V_TMO 


Symbolic Offset 


In the following text, each of the options is described under its symbolic 
offset. For example, the asynchronous option is described under RAB$V_ 
ASY. 
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Connect Service Options 


RABS$V_BIO 

Block I/O; specifies that only block I/O operations are to occur, when mixed 
record I/O and block I/O operations are allowed. This option is meaningful 
only if the FABSB_FAC FAB$V_BRO option was specified when the file was 
opened (by a Create or Open service). When the RAB$V_BIO option is set 
for the Connect service, only block I/O operations are allowed for this record 
stream. When the RAB$V_BIO option is clear for the Connect service, only 
record I/O operations are allowed when accessing a relative or indexed file 


and mixed (block I/O and record I/O) operations are allowed for sequential 
files. This option corresponds to the FDL attribute CONNECT BLOCK_IO. 


RAB$V_EOF 


End-of-file; indicates that VMS RMS is to position the record stream to the 
end of the file for the connect record operation only. 


This option corresponds to the FDL attribute CONNECT END_OF_FILE. 


RABSV_RAH, RABSV_WBH 
Read ahead and write behind; see explanation under “Performance Options”. 


Note that the first three indexed file options have limited application with 
relative files. See the Guide to VMS File Applications for details. 


The indexed file options may be enabled or disabled during any record 
operation. 


As shown in the following chart, synonyms have been defined for the two 
key search options, RAB$V_KGT and RAB$V_KGE, to reflect the functional 
capability for processing records in ascending or descending order. DIGITAL 
recommends you use these synonyms when coding new applications. 


Search Option Synonym Definition 


RAB$V_KGE RAB$V_EONXT Return the record with an equal key 
value, or the next key value according 
to the sort order for the current key of 
reference. 


RAB$V_KGT RAB$V_NXT Return the record with the next key 
value according to the sort order for the 
current key of reference. 


Indexed File Options 


RAB$V_EQNXT 


The symbolic offset RAB$V_EQNXT is logically synonymous with the 
symbolic offset RAB$V_KGE. When you select this option and ascending 
sort order is specified, VMS RMS returns the next record having a key value 
equal to or greater than the value specified by the RAB$L_KBF and RAB$B_ 
KSZ fields. If descending sort order is specified, VMS RMS returns the next 
record that contains a key value equal to or less than the value specified by 
the RAB$L__KBF and RAB$B_KSZ fields. 
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Note: Sort order is established in the data type field (symbolic offset XAB$B_ 
DTP) of the associated XABKEY when the file is created. 


If the program specifies a RAB$V_EQNXT search and no record has a key 
value identical to the specified search value, VMS RMS returns the record 
with the next key value according to the specified sort order. (See the 
description of the RAB$V_NXT bit.) 


If the program specifies a RAB$V_EQNXT search and a record with a key 
value identical to the search key is found, VMS RMS returns the record 
regardless of sort order. 


For example, consider an ascending-key indexed file having three records, A, 
B, and C, where the key for each record is the record itself. When the file is 
processed sequentially, the records are encountered in the following order: 


A B C 


If the program does a RAB$V_EQNMT search specifying the B key value, 
VMS RMS returns record B. 


If this file is reorganized as descending-key indexed file and it is processed 
sequentially, the records are encountered in the following order: 


C B A 


Again, when the program does a RAB$V_EQNMXT search specifying the B key 
value, VMS RMS returns record B. 


If neither a RAB$6V_EQNXT search nor a RAB$V_NXT search (logically 
synonymous with RAB$V_KGT) is specified, an exact key match is required 


unless a generic key match is specified. (See the description of the RAB$B_ 
KSZ bit.) 


This option corresponds to the FDL CONNECT attribute KEY_GREATER— 
EQUAL. 


RABSV_KGE 


This option is logically synonymous with the RAB$V_EQNXT option and is 
described under RAB$V_EQNXT. 


RAB$V_KGT 


This bit is logically synonymous with the RAB$V_NXT option and is 
described under RAB$V_NXT. 


RABSV_LIM 

This option is supported for indexed files only. It permits you to use VMS 
RMS as a limit sensor when accessing a file sequentially. When the RAB$V_ 
LIM bit is set, the key value defined by the RAB$L_KBF and RAB$B_KSZ 
fields (limit key value) is compared to the key value in each record as it is 
accessed. When a record is accessed that has a key value different from the 
limit key value, VMS RMS returns the RMS$_OK_LIM success status code. 


This option corresponds to the FDL attribute CONNECT KEY_LIMIT. 


RAB$V_LOA 


This option is supported for indexed files only. It specifies that VMS RMS is 
to load buckets according to the fill size established when the file is created. 
The bucket fill size is established in the XABSW_DFL and XAB$W_IEFL fields 
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Note: 


of the key definition XAB. If LOA is not specified, VMS RMS ignores the 
established bucket fill size; that is, buckets are completely filled. 


This option corresponds to the FDL attribute CONNECT FILL_BUCKETS. 


RABSV_NXT 

The symbolic offset (RAB$V_NXT) is logically synonymous with the symbolic 
offset RAB$V_KGT. When the bit is set and ascending sort order is specified, 
VMS RMS returns the next record having a key value greater than the value 
specified by the RAB$L_KBF and RAB$B_KSZ fields. If descending sort 
order is specified, VMS RMS returns the next record having a key value 

less than the value specified by the RAB$L_KBF and RAB$B_KSZ fields. 

If neither RAB$V_KGT nor RAB$V_EQNXT (logically synonymous with 
RAB$V_KGE) is specified, an exact key match is required. 


Sort order is established in the data type XAB$B_DTP field of the 
associated XABKEY when the file is created. 


The key searching usually produces different results depending on the 
specified sort order. For example, consider an ascending-key indexed file 
having three records, A, B, and C, where the key for each record is the record 
itself. When the file is processed sequentially, VMS RMS returns the records 
in the following order: 


A B C 


If the program does a RAB$V_KGT search specifying the B key value, VMS 
RMS returns record C. 


If this file is reorganized as descending-key indexed file and is processed 
sequentially, the records are returned in the following order: 


C B A 


Now when the program does a RAB$V_KGT search specifying the B key 
value, VMS RMS returns record A. 


This option corresponds to the FDL CONNECT attribute KEY_GREATER— 
THAN. 


Miscellaneous Options 


RAB$SV_TMO 


Timeout; in addition to its use for terminals and preventing delays due 

to record locks (described later), the RAB$V_TMO option serves a special 
purpose for mailbox devices. If specified in combination with a timeout value 
of 0 (RAB$B_TMO), Get and Put services to mailbox devices use the IO$M_ 
NOW modifier. Doing so causes the operation to complete immediately, 
instead of synchronizing with another cooperating writer or reader of the 
mailbox. . 


This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE 
and is not supported for DECnet operations. 


See the VMS I/O User’s Reference Volume for a further discussion of 
mailboxes. 
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Performance Options 


RABS$V_ASY 

Asynchronous; indicates that this I/O operation is to be performed 
asynchronously. When you specify RAB$V_ASY, you pass the address of 
the RAB as an argument to the AST routine. VMS RMS returns control to 
your program as soon as an I/O operation is initiated, even though that 
operation may not yet be completed. This option is normally used with 
a Wait service to synchronize with operation completion; it is ignored for 
process-permanent files. 


The RAB$V_ASY option corresponds to the FDL attribute CONNECT 
ASYNCHRONOUS. 


RAB$V_FDL 


Fast delete; this option reduces the time required to delete records in indexed 
files. The saving in time is achieved by temporarily avoiding the processing 
needed to eliminate pointers from alternative indexes to the record. However, 
there is a cost associated with this option. First, the structural linkage from 
the alternate indexes remains in place but has no utility; therefore, a certain 
amount of space is wasted. Second, if the program tries to access the deleted 
record from an alternate index, VMS RMS traverses the linkage, finds the 
record no longer exists and then generates a “nonexistent record” error 
message which the program must process. 


You should take the fast delete option only if the immediate saving in time is 
of greater benefit to you than the associated costs in space and overhead. 


This option corresponds to the FDL attribute CONNECT FAST_DELETE. 
RAB$V_LOC 


Locate mode; under specified conditions, you have the option of specifying 
locate mode instead of move mode, the default method of buffer handling. 
In locate mode, your program accesses records directly in an I/O buffer. 
Thus, VMS RMS does not have to move records between I/O buffers and an 
application program buffer. The RAB$V_LOC option activates locate mode. 
VMS RMS supports this option for the Get service only. The conditions that 
may prohibit the use of the locate mode option are given in the following list: 


e Record crosses block boundaries. 

¢ The FAB$B_FAC field FAB$V_UPD option is set. - 

¢ There are multiple record streams. 

e Process-permanent files are accessed indirectly. 

¢ Records are compressed in indexed Prolog 3 files. 

In move mode, VMS RMS transfers individual records between I/O buffers 
and your program buffer. When you invoke a Get service, VMS RMS reads 
a block or set of blocks (for sequential files) or a bucket (for relative and 
indexed files) into an I/O buffer. VMS RMS then selects the desired record 


from the buffer and moves it into the program-specified location. Locate 
mode eliminates the last step. 


This option corresponds to the FDL attribute CONNECT LOCATE_MODE 
and it is not supported for DECnet operations; move mode is always used. 
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RAB$V_RAH 


Read-ahead; used with multiple buffers (see RAB$B_MBEF) to indicate read- 
ahead operations. VMS RMS issues I/O requests as soon as possible when 

a buffer is needed. When the first buffer is filled, the I/O operation takes 
place for the first buffer as the second buffer receives the next record; the 
second buffer soon becomes filled and the next record is read into the first 
buffer as the I/O operation for the second buffer occurs. The system does 
not have to wait for I/O completion, which permits an overlapping of input 
and computing. Read-ahead is ignored for unit record device I/O and is 
supported only for the nonshared sequential file organization. If the RABSV_ 
RAH option is specified when the multibuffer count (RAB$B_MBEF) is 0, 

two buffers are allocated to allow multibuffering. If two or more buffers are 
specified, multibuffering is allowed regardless of what was specified to the 
Connect service. Conversely, if a buffer count of 1 is specified, multibuffering 
is disabled regardless of what was specified to the Connect service. 


This option corresponds to the FDL attribute CONNECT READ_AHEAD and 
it is not supported for DECnet operations. 


RAB$V_SYNCSTS 


When you select this option, VMS RMS returns the success status RMS$_ 
SYNCH if the requested service completes its task immediately. The most 
common reason for not completing a task immediately is that the task 
involves I/O operations. 


The status RMS$_SYNCH is returned in RO only. Refer to the RAB$L_STS 
field for the actual success status or failure status of the task. 


The RAB$V_SYNCSTS option should be used in conjunction with the 
RAB$V_ASY option. 


RAB$V_WBH 


Write-behind; used with multiple buffers (see RAB$B_MBF). When one 
buffer is filled, the next record is written into the next buffer while the 

I/O operation takes place for the first buffer. The system does not have 

to wait for I/O completion, which allows for an overlapping of computing 
and output. Write-behind is ignored for unit record devices. This option 

is implemented only for the nonshared sequential file organization. If the 
RAB$V_WBH option is specified when the multibuffer count (RAB$B_MBF) 
is 0, two buffers are allocated to allow multibuffering. If two or more buffers 
are specified, multibuffering is allowed regardless of what was specified to the 
Connect service. Conversely, if a buffer count of 1 is specified, multibuffering 
is disabled regardless of what was specified to the Connect service. 


This option corresponds to the FDL attribute CONNECT WRITE_BEHIND 
and it is not supported for DECnet operations. 


Put Service Options 


RABSV_TPT 


Truncate-on-put; specifies that a Put or Write service using sequential record 
access mode can occur at any point in the file, truncating the file at that point. 
The end-of-file mark is set to the position immediately following the last byte 
written. . 
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Truncating a file deletes all records beyond the point of truncation. In a 
shared environment, the application must ensure proper interpretation of a 
truncate operation. The process must have specified truncate access by setting 
the FAB$V_TRN option in the FAB$B_FAC field when the file was opened or 
created. 


This option applies only to sequential files and corresponds to the FDL 
attribute CONNECT TRUNCATE_ON_PUT. 


RAB$V_UIF 


Update-if; indicates that if a Put service is invoked for a record that already 
exists in the file, the operation is converted to an Update. This option is 
necessary to overwrite (as opposed to update) an existing record in relative 
and indexed files. Indexed files using this option must not allow duplicates 
on the primary key. The process must have specified Update access by setting 
the FAB$V_UPD option in the FAB$B_FAC field when the file was opened or 
created. 


When using this option with shared files and automatic record locking, you 
should be aware that the Put service, unlike the Update service, briefly 
releases record locks until it is determined that an Update should take 
place. At that point, the record is relocked for the Update operation. Note 
that during the time the Put operation is being converted into an Update 
operation, it is possible that another record stream could update or delete the 
record. 


This option corresponds to the FDL attribute CONNECT UPDATE_IF. 


The record-processing options related to controlling record locking are 
described below. Except as noted, these options apply to all file organizations 
and may be selected for each operation. 


Record Locking Options 


RAB$V_NLK 


Do not lock record; specifies that the record accessed through a Get or Find 
service is not to be locked. The RAB$V_NLK option takes precedence over 
the RABSV_ULK option. 


This option corresponds to the FDL attribute CONNECT NOLOCK. 
RABSV_NXR 


Nonexistent record processing; specifies that if the record directly accessed 
through a Get or Find service does not exist (was never inserted into the file 
or was deleted), the service is to be performed anyway. For a Get service, 
the previous contents of a deleted record are returned. The processing of a 
deleted record returns a completion status code of RMS$_OK_DEL, and the 
processing of a record that never existed returns RMS$_OK_RNF. 


This option applies only to relative files and it corresponds to the FDL 
attribute CONNECT NONEXISTENT_RECORD. 


RAB$V_REA 

Lock record for read; specifies that the record is to be locked for a read 
operation for this process, while allowing other accessors to read the record 
(but not to modify the record). Use this option only when you do not want 
the file to be modified by any subsequent activities. Use the RAB$V_RLK 
option to allow possible subsequent modification of the file. 


This option corresponds to the FDL attribute CONNECT LOCK_ON_READ. 
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RAB$V_RLK 


Lock record for write; specifies that a user who locks a record for modification 
is allowing the locked record to be read by other accessors. If both RAB$V_ 
RLK and RAB$V_REA option are specified, the RAB$V_REA option is 
ignored. The RAB$V_NLK option takes precedence over all others. 


This option corresponds to the FDL attribute CONNECT LOCK_ON_— 
WRITE. 


RAB$V_RRL 


Read regardless of lock; read the record even if another stream has locked the 
record. This option allows the reader some control over access. If a record 

is locked against all access and this bit is set for either a Put or Get service 
request, the record is returned with alternate status RMS$_OK_RRL. 


This option corresponds to the FDL attribute CONNECT READ_ 
REGARDLESS. 


RAB$V_TMO 

Timeout; specifies that if the RAB$V_WAT option was specified, the RAB$B_ 
TMO field contains the maximum time value, in seconds, to be allowed for 

a record input wait caused by a locked record. If the timeout period expires 
and the record is still locked, VMS RMS aborts the record operation with the 
RMS$_TMO completion status. Note that the maximum time allowed for a 
timeout is 255 seconds. Other functions of the RAB$6V_TMO option are listed 
under “Miscellaneous Options.” 


This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE 
and it is not supported for DECnet operations. 


RABS$V_ULK 

Manual unlocking; prohibits VMS RMS from automatically unlocking records. 
Instead, once locked (through a Get, Find, or Put service), a record must be 
specifically unlocked by a Free or Release service. The RAB$V_NLK option 
(above) takes precedence over the RAB$V_ULK option. 


This option corresponds to the FDL attribute CONNECT MANUAL 
UNLOCKING. 


RABSV_WAT 


Wait; if the record is currently locked by another stream, wait until it is 
available. This option may be used with the RAB$V_TMO option (see above) 
to limit waiting periods to a specified time interval. 


This option corresponds to the FDL attribute CONNECT WAIT_FOR_ 
RECORD. 


The record-processing options related to terminal devices are described 
below. These options map directly into equivalent modifiers to the QIO 
function code. For a further discussion of their effects, see the VMS I/O 
User’s Reference Volume. These options can be selected for each operation. 
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Terminal Device Options 


RAB$V_CCO 


Cancel CTRL/O; guarantees that terminal output is not discarded if the 
operator presses CTRL/O. 


This option corresponds to the FDL attribute CONNECT TT_CANCEL— 
CONTROL —O and it is not supported for DECnet operations. 


RAB$V_CVT 


Convert; changes characters to uppercase on a read from a terminal. 


This option corresponds to the FDL attribute CONNECT TT_UPCASE_— 
INPUT and it is not supported for DECnet operations. 


RAB$V_ETO 


Extended terminal operation; indicates presence of a Terminal XAB (XABTRM) 
to describe terminal input using extended terminal characteristics. Note that 
if this option is specified, all other RAB$L_ROP options specific to terminal 
devices are ignored (including the RAB$V_TMO option). 


This option is not supported for DECnet operations. 


RAB$V_PMT 


Prompt option; indicates that the contents of the prompt buffer are to be used 
as a prompt for reading data from a terminal (see RAB$L__PPBF field). 


This option corresponds to the FDL attribute CONNECT TT_PROMPT and it 
is not supported for DECnet operations. 


RABSV_PTA 


Purge type-ahead; eliminates any information that may be in the type-ahead 
buffer on a read from a terminal. 


This option corresponds to the FDL attribute CONNECT TT_PURGE_TYPE_ 
AHEAD and it is not supported for DECnet operations. 


RABS$V_RNE 


Read no echo; indicates that input data is not echoed (displayed) on the 
terminal as it is entered on the keyboard. 


This option corresponds to the FDL attribute CONNECT TT_READ_ 
NOECHO and it is not supported for DECnet operations. 


RABS$V_RNF 

Read no filter; indicates that CTRL/U, CTRL/R, and DELETE are not to be 
considered control commands on terminal input but are to be passed to the 
application program. 


This option corresponds to the FDL attribute CONNECT TT_READ_ 
NOFILTER and it is not supported for DECnet operations. 


RAB$SV_TMO 

Timeout; for terminal operations, indicates that the content of the RAB$B_ 
TMO field is to be used to determine the number of seconds allowed between 
characters received during terminal input. If the timeout period expires, 
VMS RMS returns an error status (see RABS$B_TMO). Other functions of the 
RAB$V_TMO option are listed under “Miscellaneous Options” and “Record 
Locking Options”. 
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This option corresponds to the FDL attribute CONNECT TIMEOUT_ENABLE 
and is not supported for DECnet operations. 





RAB$SW_RSZ Field 


The record size (RSZ) field contains the size, in bytes, of the record. For a 
Write service, the range is 1 through 65,535. For a Put or Update service, the 
range is 0 to the maximum value shown in Table 5-4. This field controls the 
size of a record that a Put or Update service can write, or the number of bytes 
that a Write (block I/O) service can write. This field is required for an Update 
service only if the file contains variable-length records or VFC records. 


On input from a file, VMS RMS sets this field to indicate the length, in bytes, 
of the record that a Get service transfers or that a Read service (block I/O) 
reads. 


Three notes apply to this field: 


1 After a Get service, VMS RMS places the record size in the RAB$W_RSZ 
field. On a Read service, VMS RMS sets the RAB$W_RSZ field to the 
number of bytes actually transferred. 


2 For variable with fixed-length control records, VMS RMS does not include 
the size of the fixed control area in the RAB$W_RSZ field. 


3 For block I/O operations, some devices require that an even number of 
bytes be transferred. 





RAB$L_STS Field 


The completion status code (STS) field is set by VMS RMS with the success 
or failure status codes for a record operation before returning control to your 
program. For an asynchronous operation that has been initiated but not 

yet completed, this field is 0. When the operation is complete, the field is 
updated with the completion status. See Part I for additional details about 
signaling VMS RMS status codes. Potential error codes for specific operations 
are listed with their descriptions in Part III. 





RAB$L_STV Field 
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The completion status value (STV) field communicates additional completion 
information to your program, on the basis of the type of operation and the 
contents of the completion status code field. For additional information on 
the RAB$L_STS and RAB$L_STV fields, see Part I. 


The RAB$L_STV field can be accessed using alternate symbolic offsets; 
RAB$W_STV0O is the location of the first word and RAB$W_STV2?2 is the 
location of the second word within RAB$L—STV. 
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7.23 RABSB_TMO Field 


The timeout (TMO) field indicates the maximum number of seconds, in the 
range 0 to 255, that VMS RMS should wait for an operation to conclude. If 
the operation does not conclude within the specified timeout period, VMS 
RMS returns an error status code. 


To use this field, you must also specify the RAB$V_TMO record-processing 
option. 


For a Get service using a terminal device, this value specifies the number 
of seconds to wait between the characters being typed. If you specify 0 
along with RAB$V_TMO, the current contents of the type-ahead buffer are 
returned. 


When you use a wait-on-record lock (RAB$6V_WAT) with a Get, Find, or Put 
service, this value specifies the maximum number of seconds for VMS RMS 
to wait for the record to become available. 


Note that if the RAB$B_TMO field contains a value of 0 and RAB$V_TMO 
is set when you invoke either a Get or Put service to a mailbox device, the 
operation terminates immediately, rather than waiting for another process. 
For example, if you invoke the Put service to a mailbox device with the 
RAB$B_TMO field clear, the Put service does not wait for the receiving 
process to get the record. 


This field corresponds to the FDL attribute CONNECT TIMEOUT_PERIOD 
and it is not supported for DECnet operations. 





7.24 RABS$L_UBF Field 


Note: 


The user record buffer address (UBF) field indicates the location of a record or 
block buffer. 


When you invoke the GET service, RMS takes control of the record buffer 
and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 


This field contains the symbolic address of a work area (buffer) within your 
program. The size of this buffer must be defined in the RAB$W_USZ (user 
record area size) field. 


When you invoke a Get service, this field must contain the buffer address, 
regardless of the record transfer mode (locate or move). This option also 
applies when you invoke the Read service for block I/O. However, a Put or 
Write service never needs a user buffer. 





7.25 RABSW_USZ Field 


The user record buffer size (USZ) field indicates the length, in bytes, of the 
user record or block buffer. This field contains a numeric value representing 
the size of the buffer, in the range of 1 through 65,535. 


The user record buffer should be large enough to contain the largest record in 
the file. If the buffer is not large enough on an operation with a Get service, 
VAX RMS moves as much of the record as possible into the buffer and returns 
a warning status code. 
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The value in this field specifies the transfer length, in bytes, for block 1/O 
operations with a Read service and for a Get service to UDF (undefined) 
format sequential files. 





RABS$L_XAB Field 


The extended attribute block address (XAB) field contains the symbolic 
address of an XAB control block that you want to use when performing 
an operation such as a Get service for a terminal device. A value of 0 (the 
default) indicates no XABs for this record stream. 


For certain record operations, you can associate XABs with a RAB to convey 
additional attributes about an operation. (See Part I for the description of an 
XAB.) 
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The allocation control XAB (XABALL) provides additional control over file or 
area space allocation on disk devices in order to optimize performance. In the 
following descriptions, the terms file and area are synonymous for sequential 
and relative files because these file organizations are limited to a single area 
(Area 0). 





8.1 Summary of Fields 


When VMS RMS uses a XAB to create or extend an area, the following 
XABALL fields duplicate and take precedence over associated fields in the 
related FAB: 


e Allocation quantity (ALQ) field, XAB$L_ALQ, overrides FAB$L__ALQ 
¢ Bucket size (BKZ) field, XAB$B_BKZ, overrides FAB$B_BKS 


e Default extension quantity (DEQ) field, XABSW_DEQ, overrides FABSW_ 


DEQ 


¢ The XAB$V_CBT and XAB$V_CTG options of the allocation options field, 
XAB$B_AOP, override the FAB$V_CBT and FAB$V_CTG options of the 
file-processing options field, FAB$L__FOP 


When opening a file or displaying a file’s attributes, VMS RMS outputs 
appropriate information to your program using these fields. 


The symbolic offset, size, FDL equivalent, and a brief description of each 
XABALL field are presented in Table 8-1. 


Table 8-1 XABALL Fields 


Field Offset 


XAB$B_AID 
XAB$B_ALN 
XAB$L_ALO 
XAB$B_AOP 
XAB$B_BKZ 
XAB$B_BLN? 
XAB$B_.COD? 
XAB$W-_DEQ 
XAB$L_LOC 
XAB$L_NXT 


Size 


(Bytes) 


1 
1 
4 
1 
1 
1 
1 
2 
4 
4 


FDL Equivalent 


AREA n 

AREA POSITION' 
AREA ALLOCATION 
AREA' 

AREA BUCKET_SIZE 
None 

None 

AREA EXTENSION 
AREA POSITION 
None 


Description 


Area identification number 
Alignment boundary type 
Allocation quantity 
Allocation options 

Bucket size 

Block length 

Type code 

Default extension quantity 
Location 

Next XAB address 


'This field contains options; corresponding FDL equivalents are listed in the description of the field. 


2This field is statically initialized by the $XABALL macro to identify this contro! block as a XABALL. 
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Table 8-1 (Cont.) XABALL Fields 


Size 
Field Offset (Bytes) FDL Equivalent Description 
XAB$W_FFI 6 AREA POSITION FILE_ID Related file identifier 
or FILE_NAME 
XAB$S$W_VOL 2 AREA VOLUME Related volume number 


Each XABALL field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $XABALL macro and the $XABALL— 
STORE macro are described in Appendix B. 





8.2 XAB$B_AID Fields 


VMS RMS uses the area identification number (AID) field to determine which 
area within a file is supported by this XAB. Note that sequential and relative 
files are limited to area 0. 


The area is identified by a numeric value in the range 0 through 254 (default 
is 0) and is most appropriate for use with index files having multiple areas 
allocated. 


This field corresponds to the FDL attribute AREA n where n indicates the area 
number. 





8.3 XAB$B_ALN Field 
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The alignment boundary type (ALN) field gives you several options for 
aligning the allocated area. VMS RMS uses this field in conjunction with 
the XAB$L_LOC field and with the XAB$W_RFI field to provide precise 
positioning control of the area or area extension. 


The XAB$B_ALN field is a keyword value field in which an alignment 
boundary option is defined by a symbolic constant value. For example, the 
cylinder boundary option has a symbolic constant value of XAB$C_CYL. 


Note that if no value is defined for this field, VMS RMS assumes the 
XAB$C_ANY option (no additional positioning control desired). Additional 
positioning control is not supported for DECnet operations. 


The XAB$B_ALN field corresponds to the FDL attribute AREA POSITION. 
The following list describes the options for the XAB$B_ALN field: 


Options 


XABS$C_ANY 


Any allocation; specifies that no positioning control over the area is desired. If 
this option is selected, the XAB$L_LOC and XAB$W_RFI fields are ignored. 


This option corresponds to the FDL attribute AREA POSITION NONE. 
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XAB$C_CYL 
Specifies that the area boundary begin at the cylinder number identified by 
the location field XAB$L_—LOC. 


This option corresponds to the FDL attribute AREA POSITION CYLINDER. 


XABS$C_LBN 


Specifies that the area boundary begin at the logical block number identified 
by the location field XAB$L_—LOC. 


This option corresponds to the FDL attribute AREA POSITION LOGICAL. 


XABSC_RFI 


This option is used only for extending an area. It specifies that the area 
extension begin as close as possible to the file identified by the related-file- 
identification field (XAB$W_RFI), and that the extent begin with the VBN 
specified by the location field XAB$L_—LOC. 


This option corresponds to the FDL attribute AREA POSITION FILE_ID or 
AREA POSITION FILE_NAME. If you try to use this option with DECnet 
operations, VMS RMS automatically replaces it with the XAB$C_ANY option. 


XABS$C_VBN 


This option applies to area extension only. It specifies that the area extension 
begin as close as possible to the virtual block number identified by the 
location field XAB$L_—LOC. 


This option corresponds to the FDL attribute AREA POSITION VIRTUAL. 





8.4 XABS$L_ALO Field 


This field defines the number of blocks to be initially allocated to an area 
when it is created using a Create service, or the number of blocks to be added 
to an area when it is explicitly extended using an Extend service (as opposed 
to automatic extension). In both cases, this field overrides the allocation 
quantity in the associated FAB (see Chapter 5). 


The XAB$L_ALQ field accepts numeric values of up to 4,294,967,295 for 
initial allocation, but the allocation is limited by the number of blocks 
available on the device. 


When you create a new area using the Create service, VMS RMS interprets 
the value in the XAB$L_ALQ field as the number of blocks for the area’s 
initial extent. If the value is 0, VMS RMS allocates a minimum number of 
blocks depending on the file organization. For example, VMS RMS allocates 
only the number of blocks needed for the key and area definitions with 
indexed files. 


When you use either the Create or Extend services with indexed files, VMS 
RMS rounds the allocation quantity value up to the next cluster boundary 
and returns this value to the program in the XAB$L_ALQ field. VMS RMS 
uses this value as the extension value when you extend an existing area using 
the Extend service, unless the program changes the value before invoking the 
Extend service. Note that the value 0 is not acceptable for extending an area. 
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8.5 XAB$B_AOP Field 


The allocation options (AOP) field lets you specify a particular type of 
allocation. 


This field is a binary options field where one or more options may be selected 
by setting the appropriate bits. Each option is identified by a symbolic offset 
and has a mask value; for example, the CBT option has an offset of XAB$V_ 
CBT and a mask value of XAB$M_CBT. 


The options for the XAB$B_AOP field are summarized in the following list. 


Options | 
XABSV_CBT 


Contiguous best try; indicates that the allocation or extension should use 
contiguous blocks, on a “best effort” basis. This option overrides the FAB$L_ 
FOP field FAB$V_CBT option. 


This option corresponds to the FDL attribute AREA BEST_TRY_ 
CONTIGUOUS. 


XAB$V_CTG 


Contiguous; indicates that the initial allocation extension must use contiguous 
blocks only; the allocation fails if the requested number of contiguous blocks 
is not available. If this is the initial allocation and only a single area is 
specified, the file is marked contiguous. This option overrides the FAB$L — 
FOP field FAB$V_CTG option. 


This option corresponds to the FDL attribute AREA CONTIGUOUS. 


XAB$V_HRD 


Hard; indicates that if the requested alignment cannot be performed, an error 
will be returned. By default, the allocation is performed as near as possible to 
the requested alignment. 


Note that the XAB$V_HRD option is applicable only to XAB$C_CYL and 
XAB$C_LBN alignment boundary types, specified by the XAB$B_ALN field. 


This option corresponds to the FDL attribute AREA EXACT_POSITIONING. 


XAB$V_ONC 


On cylinder boundary; indicates that VMS RMS is to begin the allocation on 
any available cylinder boundary. 


This option corresponds to the FDL attribute AREA POSITION ANY_ 
CYLINDER. 
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8.6 XAB$B_BKZ Field 


When VMS RMS creates relative and indexed files, this field specifies bucket 
size using numeric values ranging from 0 through 63 to represent the number 
of blocks in a bucket. If this argument is omitted, or if a value of 0 is 
inserted, VMS RMS uses a default size equal to the minimum number of 
blocks required to contain a single record. For RMS-11 processing, the bucket 
size must be less than or equal to 32 blocks. 


When calculating the bucket size, you must consider the control information 
(overhead) associated with each bucket. Note that some record types contain 
control bytes and to calculate the overhead you must multiply the number of 
records per bucket by the number of control bytes per record. See the Guide 
to VMS File Applications for more information. 


The FDL editor can be used to calculate efficient bucket sizes for indexed files. 
(For information about the FDL editor, see the VMS File Definition Language 
Facility Manual. 


When you create a file, VMS RMS uses this field as input to determine the 
specified bucket size and upon conclusion, uses the field to output the bucket 
size. Because relative files are limited to one area, this field specifies the size 
for all buckets in the file. For indexed files, you can specify a different size 
for each area using this field in the appropriate XABALL. 


When you open an existing file, VMS RMS uses this field to output the bucket 
size to your program. 


The value in this field overrides the contents of the bucket size field of the 
FAB on a Create service (see Chapter 5). 


You can specify multiple areas for a single index by having the XAB$B_IAN 
and XAB$B_LAN fields in the key definition XAB (XABKEY) indicate that the 
lowest level of the index and the remainder of that index occupy different 
areas (defined by different XABALLs). However, the number of blocks 

per bucket (XAB$B_BKZ value) must be the same for the entire index of a 
particular key. If multiple areas are specified for an index and if the XAB$B_ 
BKZ values are not the same, VMS RMS returns an error because the values 
for one index must be the same. However, if you specify the XAB$B_BKZ 
field for at least one area and use the default (0) for the XAB$B_BKZ field 
of a different area (or areas) of the same index, VMS RMS uses the largest 
XAB$B_BKZ value specified among the XABALL control blocks to determine 
the bucket size for that index. 


This field corresponds to the FDL attribute AREA BUCKET_SIZE. 





8.7 XAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABALL, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALLEN (this is done by the $XABALL macro). 


8.8 


8.9 


8.10 


8.11 


Allocation Control XAB (XABALL) 
8.8 XAB$B_COD Field 





XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block as 
a XABALL. Once set, this field must not be altered unless the control block 
is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ALL (this is done by the $XABALL macro). 


XABSW_DEO Field 


The default extension quantity (DEQ) field specifies the number (0 to 65,535) 
of blocks to be added when VMS RMS automatically extends the area. If you 
specify 0, the VMS RMS provides a default extension value. 


The value in this field overrides the contents of the default extension quantity 
field of the FAB (see Chapter 5). 


This field corresponds to the FDL attribute AREA EXTENSION. 





XAB$L_LOC Field 


The location (LOC) field contains a numeric value that indicates the beginning 
point for area allocation. VMS RMS refers to the location field when 
executing a Create or Extend service, but only if the XABSB_ALN field 
specifies an alignment option. The way the XAB$L_LOC field is used 
depends on the value specified for the XABSB_ALN field (a binary options 
field). The beginning point for the allocation is determined as follows: 


e If the XAB$B_ALN field XAB$C_CYL option is specified, the location 
number is the cylinder number (0 through the maximum cylinder number 
on the volume) where the allocation begins. 


e If the XAB$B_ALN field XAB$C_LBN option is specified, the location 
number is the logical block number (0 through the maximum number of 
blocks on the volume) where the allocation begins. 


e If the XAB$B_ALN field XAB$C_VBN or XAB$C_RFI option is specified, 
the location number is the virtual block number (1 through the maximum 
number of blocks in the file) where the allocation begins. This applies 
only to the Extend service. If the number 0 is specified, or if the number 
is omitted during an Extend service, VMS RMS places the file extension 
as near to the end of the file as possible. 


This field corresponds to the FDL attribute AREA POSITION. 





XAB$L_NXT Field 


The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 
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8.12 XABSW_RFI Field 


The related file identification (RFI) field allows you to position files or areas of 
an indexed file close to a specified file. 


This field contains the 3-word file identification value of the related file. 

A value of 0,0,0 (the default) indicates that the current file is to be used. 
Specifying the XAB$B_ALN field XAB$C_RFI option and specifying the 
XAB$W_RFI field as 0,0,0 are equivalent to specifying the XAB$B_ALN field 
XAB$C_VBN option. 


You can view the file identification of a file using the DCL command 
DIRECTORY with the /FULL qualifier. 


The file is created or extended as near to the specified related file as possible 
at the virtual block number specified by the LOC argument. 


The XAB$W_RFI field is ignored unless the XAB$B_ALN field is set to 
XAB$C_RFI. It is also ignored for DECnet operations. 


This field corresponds to the FDL attribute AREA POSITION FILE_ID or 
AREA POSITION FILE_NAME. 





8.13. XABSW_VOL Field 


The relative volume number (VOL) field indicates the specific member of a 
volume set upon which the file is to be allocated. 


This field contains an integer in the range 0 through 255. The default is 0, 
specifying the “current” member of the volume set. 


Note that volume placement will be performed only if an alignment type in 
the XAB$B_ALN field is either XAB$C_CYL or XAB$C_LBN (you cannot 
specify XAB$C_VBN or XAB$C_RFI alignment types). If the XAB$B_ALN 
field contains a value of 0, placement of the file within the volume set will be 
at the discretion of the system, regardless of the contents of the XAB$W_VOL 
field. 


This field corresponds to the FDL attribute AREA VOLUME. 


9 Date and Time XAB (XABDAT) 


The date and time XAB (XABDAT) block provides extended control of the 
date and time of the file’s creation, revision (update), backup, and expiration. 





9.1 Summary of Fields 


VMS RMS sets certain values for date and time and returns them in XABDAT 
fields for your inspection. You can override these system-supplied values 
through the use of an XABDAT as input to a Create service. Note that date- 
time values are expressed in either absolute (positive) or delta (negative) 
format, and several system services are available for date-time conversion 
and use (see Example 3-1 in Chapter 3 of this manual and the VMS System 
Services Reference Manual). 


The symbolic offset, size, FDL equivalent, and a brief description of each 
XABDAT field are presented in Table 9-1. 


Table 9-1 XABDAT Fields 


Field Offset eee FDL Equivalent Description 
XAB$Q_BDT' 8 DATE BACKUP Backup date and time 
XAB$B_BLN? 1 None Block length 
XAB$Q_CDT' 8 DATE CREATION Creation date and time 
XAB$B_COD? 1 None Type code 

XAB$O _EDT 8 DATE EXPIRATION Expiration date and time 
XAB$L_NXT 4 None Next XAB address 
XAB$Q_RDT' 8 DATE REVISION Revision date and time 
XAB$W_RVN' 2 FILE REVISION Revision number 


'This field cannot be initialized by the $XABDAT macro. 


2This field is statically initialized by the $XABDAT macro to identify this control block as a 
XABDAT. 


Table 9-2 describes how the fields of the XABDAT block are used by the 
VMS RMS services. 
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Table 9-2 Services and the XABDAT Control Block 


Service XAB$Q_BDT XAB$Q_CDT XAB$Q_EDT XAB$Q_RDT, XABSW_RVN 
Close Not used Not used Not used Not used 

Create Input Input Input Input’ 

Display Output Output Output Output 

Erase Not used Not used Not used Not used 

Extend Not used Not used Not used Not used 

Open Output Output Output Output 


'The XAB$Q_RDT field for a Create service is superseded by the current date and time on a Close service. Use the 
XABRDT block to specify the XAB$Q_RDT field (see Chapter 15). 


The following notes apply to the use of XABDAT fields by VMS RMS services: 


1 If the user specifies the XABSQ_CDT or XAB$Q_RDT field in the 
XABDAT as 0 (either explicitly or by default) and if the specified field is 
used as an input field by the service, it is replaced with the current date 
and time. 


2 If the Create service is invoked with a FAB that specifies the FAB$L__FOP 
field FABS$V_CIF (create-if) option and if the file to be created already 
exists, the Create service is processed like an Open service and the fields 
listed above are output fields. 


Each XABDAT field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $XABDAT macro and the $XABDAT_ 
STORE macro are described in Appendix B. 





XAB$Q_BDT Field 


The backup date and time (BDT) field contains a 64-bit binary value 
expressing the date and time when the file was most recently backed up. 
Note that this field is limited to a granularity of 1 second for remote files. 


This field corresponds to the FDL attribute DATE BACKUP. 





XABS$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABDAT in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DATLEN (this is done by the $XABDAT macro). 
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XAB$Q_CDT Field 


The creation date and time (CDT) field contains a 64-bit binary value 
expressing the date and time when the file was created. Note that this 
field is limited to a granularity of 1 second for remote files. 


This field corresponds to the FDL attribute DATE CREATION. 


XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block 

as an XABDAT. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_DAT (this is done by the $SXABDAT macro). 


XAB$Q_EDT Field 


The expiration date and time (EDT) field contains a 64-bit binary value that 
indicates the date and time after which a file residing on a disk device may be 
considered for deletion by the system manager. For files residing on magnetic 
tape devices, the XAB$Q_EDT field sets the date and time after which you 
can overwrite the file. Note that this field is limited to a granularity of 1 
second for remote files. 


This field corresponds to the FDL attribute DATE EXPIRATION. 


XAB$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 





XAB$Q_RDT Field 


The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time when the file was last updated. Note that 
this field is limited to a granularity of 1 second for remote files. 


This field corresponds to the FDL attribute DATE REVISION. 





XABSW_RVN Field 


The revision number (RVN) field contains a numeric value that indicates the 
number of times this file was opened for write operations. 


This field corresponds to the FDL attribute FILE REVISION. 
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10 File Header Characteristic XAB (XABFHC) 


The file header characteristic XAB (XABFHC) contains information about a file 
that is stored in the file header. VMS RMS copies the file characteristics into 

this XAB whenever an Open or Display service executes. The XABFHC fields 
are then available for you to examine during processing. 


Note that for unshared sequential files, or sequential files shared using the 
FAB$V_UPI option, the values in the end-of-file block (XAB$L_EBK), first 
free byte in the end-of-file block (XAB$W_FFB), and longest record length 
(XAB$W_LRL) fields correspond to the values at the time of the last Close or 
Flush service. 


On a Create service, only the longest record length (XAB$W_LRL) field of this 
XAB is used as input, and then only if the record format is not fixed length. 
All other fields are used only as output from the VMS RMS services. 





10.1 Summary of Fields 


The symbolic offset, size, and a brief description of each RAB field are 
presented in Table 10-1. Note that many of these fields are also available in 
the FAB. 


Table 10-1 XABFHC Fields 


Size 
Field Offset (bytes) Description 
XAB$B_ATR' 1 Record attributes; equivalent to FAB$B_RAT 
XAB$B_BKZ' 1 Bucket size; equivalent to FABS$B_BKS 
XAB$B_BLN? 1 Block length 
XAB$B_COD? 1 Type code 
XAB$SW_DxQ! 2 Default file extension quantity; equivalent to 
FABSW_DEQ 
XAB$L_EBK' 4 End-of-file block 
XABSW_FFB' 2 First free byte in the end-of-file block 
XAB$SW_GBC' 2 Default global buffer count 
XAB$L_HBK' 4 Highest virtual block in the file; equivalent to 
FAB$SL_ALQ 
XAB$B_HSZ' 1 Fixed-length control header size; equivalent to 
. FAB$B_FSZ 
XAB$W_LRL' 2 Longest record length 


'This field cannot be initialized by the $XABFHC macro. 


2This field is statically initialized by the $XABFHC macro to identify this control block as a 
XABFHC. 
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Table 10—1 (Cont.) XABFHC Fields 





Size 

Field Offset (bytes) Description 

XAB$W_MRZ' 2 Maximum record size; equivalent to FAB$W_ 
MRS 

XABS$L_NXT 4 Next XAB address 

XAB$B_RFO' 1 File organization and record format; combines 
FAB$B_RFM and FAB$B_ORG 

XABSL_SBN' 4 Starting logical block number for the file if it is 
contiguous; otherwise this field is O 

XABSW_ 2 Version limit for the file 


VERLIMIT! 





'This field cannot be initialized by the $XABFHC macro. 





Each XABFHC field is described below. There are no FDL equivalents for 
the XABFHC fields. Unless indicated otherwise, each field is supported for 
DECnet operations using remote files with a VMS system as the remote node. 
Note that the words “DECnet operations” in the following descriptions refer 
to remote file operations between two VMS systems. See the VMS Networking 
Manual for information about the support of VMS RMS options for remote 
file access to other systems. 


The format and arguments of the $XABFHC macro and the $XABFHC_ 
STORE macro are described in Appendix B. 


10.2 - XABS$B_ATR Field © 
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The record attributes (ATR) field indicates the record attributes (special control 
information) associated with each record in this file. This field is equivalent 
to the FAB$B_RAT field. 


This field is a binary options field where each record attribute has a 
corresponding bit assignment. Options are identified using mnemonics. 
Each option in the field has its own symbolic offset and constant value. For 
example, the CR record attribute has the symbolic offset XAB$V_CR and the 
mask value XAB$M_CR. The record attribute options are described in the 
following list: 


Options 
XAB$V_BLK 


Records do not cross block boundaries in sequential files. 


XABS$V_CR 
Each record is preceded by a line feed and followed by a carriage return. 


XABS$V_FTN 
Each record contains a FORTRAN (ASA) carriage return in the first byte. 


XABS$V_PRN 
Print file format. 
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For more information about the XAB$B_ATR field, refer to the description of 
the FAB$B_RAT field in Chapter 5. 





10.3. XAB$B_BKZ Field 


The bucket size (BKZ) field specifies the number of blocks in each bucket of 
the file. It is equivalent to the FAB$B_BKS (or XAB$B_BKZ) field and is used 
only for relative or indexed files. 


This field contains a numeric value in the range of 0 to 63. 


For more information about the XAB$B_BKZ field, refer to the description of 
the FAB$B_BKS field in Chapter 5 and the description of the XAB$B_BKZ 
field in Chapter 8. 


10.4 XABS$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABFHC, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHCLEN (this is done by the $XABFHC macro). 


10.5 XABSB_COD Field 


The type code (COD) field is a static field that identifies this control block 

as an XABFHC. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_FHC (this is done by the $XABFHC macro). 


10.6 XABSW_DXO Field 


The default file extension quantity (DXQ) field specifies the number of blocks 
to be added when a disk file is extended automatically. This automatic 
extension occurs whenever your program performs a Put or Write service and 
the currently allocated file space is exhausted. 


This field is equivalent to the FABSW_DEQ (or XAB$W_DEQ) field; it 
contains a numeric value in the range 0 through 65,535, which is rounded up 
to the value of the next cluster boundary. 


For more information about the XAB$W_DXQ field, refer to the description of 
the FAB$B_DEQ field in Chapter 5 and the description of the XABSW_DEQ 
field in Chapter 8. 
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XAB$L_EBK Field 


When you open a file, VMS RMS stores the VBN of the physical block where 
the next record will be written in the XAB$L_EBK field. For example, assume 
that a file is allocated five physical blocks and that the last record written 

to the file is at byte OFF), in the file’s second physical block. When your 
program opens this file, VMS RMS stores the VBN of the second physical 
block in XAB$L_EBK and it stores 1001, in the XAB$W_FFB field. 


If the previous block is full when you open the file, VMS RMS stores the 
first location ( 000;¢) of the next block in XABSW_FFB and the VBN of the 
next block in XAB$L_EBK. By way of contrast, in a similar situation RMS-11 
stores the last byte ( 2001¢) of the filled block in the XABSW_FFB field and 
the VBN of the filled block in the XAB$L_EBK field. 


The XAB$L__EBK field is meaningful for sequential files only. 


XABSW_FFB Field 


The first free byte in the end-of-file block (FFB) field contains the byte location 
in the end-of-file block where the next record will be written. The XAB$W_ 
FFB field is meaningful for sequential files only. 


XAB$W_GBC Field 


The default global buffer count (GBC) field contains the current global buffer 
count for this file. For more information about the XABS$W_GBC field, refer 
to the description of the FAB$W_GBC field in Chapter 5. 


This field is not supported for DECnet operations; it is ignored. 





XAB$L_HBK Field 


The highest virtual block (HBK) field contains the virtual block number 
currently allocated to this file. It is equivalent to the FAB$L_ALQ field 
after a Create, Open, or Display service executes. For sequential files, the 
difference between XAB$L_HBK and XAB$L_EBK equals the number of 
blocks in the file available for additional records without extending the file. 





XAB$B_HSZ Field 


The fixed-length control header size (HSZ) field indicates the length of the 
fixed portion for records in the VFC format. It is equivalent to the FAB$B_ 
FSZ field. 


This field contains a numeric value (1 to 255) that indicates, in bytes, the size 
of the fixed-length control area. This field is not applicable to indexed files. 


For more information about the XAB$B_HSZ field, refer to the description of 
the FAB$B_FSZ field in Chapter 5. 
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10.12 XABSW_LRL Field 


The longest record length (LRL) field contains a numeric value that indicates 
the longest record currently in the file, in bytes. This value is meaningful for 
sequential files only. 


10.13 XABSW_MRzZ Field 


The maximum record size (MRZ) field indicates the size of all records in a file 
with fixed-length records, the maximum size of variable-length records, the 
maximum size of the data area for variable with fixed-length control records, 
and the cell size for relative files. It is equivalent to the FABSW_MRS field. 


This field contains a numeric value in the range applicable to the file type and 
record format (see Table 5-4), in bytes. 


For fixed-length records, the value represents the actual size of each record in 
the file. 


For variable-length records, the value represents the size of the largest record 
that can be written into the file. If the file is not a relative file, a value of 0 
is used to suppress record size checking, thus indicating that there is no user 
limit on record size. 


For variable with fixed-length control records, the value includes only the 
data portion; it does not include the size of the fixed control area. 


For more information about the XAB$W_MERZ field, refer to the description of 
the FABSW_MRS field in Chapter 5. 


10.14 XABS$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 


10.15 XABS$B_RFO Field 


The file organization and record format (RFO) field combines the FAB$B_ 
RFM and FAB$B_ORG fields using an inclusive OR. 
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Record formats are listed below. 


Record Format Description 

FIX Fixed length 

STM Stream, delimited by FF, VT, LF, or CR LF 
STMCR Stream, delimited by CR 

STMLF Stream, delimited by LF 

UDF Undefined 

VAR Variable length 

VFC Variable length with fixed control area 


The file organizations are listed below. 


File Organization Description 

IDX Indexed sequential 
REL Relative 

SEO. Sequential 


For more information about the XAB$B_RFO field, refer to the description of 
the FAB$B_ORG field and the FAB$B_RFM field in Chapter 5. 


10.16 XAB$L_SBN Field 


The starting logical block number (SBN) field contains the starting logical 
block number for a contiguous file; if the file is not contiguous, this field 
contains 0. 


10.17 XABSW_VERLIMIT Field 


The file version limit (VERLIMIT) field contains the version limit for this file. 
This value is not available if the file was opened by file ID. 


This field is not supported for DECnet operations; it is ignored. 


11 Item List XAB (XABITM) 


The item list XAB (XABITM) provides a convenient means for using item list 
information to support VMS RMS functions. An item list consists of one or 
more entries that can represent either a control function or a sensing function 
that can be passed to the application program by way of the VMS RMS 
interface. 


Within the item list, you may not include a mix of control and sensing 
items related to various VMS RMS-supported functions. However, multiple 
XABITMs may be used. VMS RMS logically ignores items that are irrelevant 
to any particular function while acting on any item that is relevant. 


Each entry in the item list addressed by the XABITM is made up of three 
longwords and a longword 0 terminates the list. VMS RMS does not validate 
the item list. If the item list is invalid, VMS RMS returns a status of RMS$_ 
XAB in the RAB$L_STS field. Figure 11-1 illustrates the format for each 
entry in the item list. 


Figure 11-1 Item Descriptor Data Structure 
31 


15 0 
buffer address 
return length address 


ZK-1705-84 










You can locate the item list anywhere within the readable address space for 
a process but any buffers required by the related function must be located in 
read/write memory. 


The format and arguments of the $XABITM macro are defined in Appendix B. 


For VMS Version 5.0, the XABITM control block supports enhancements 

to network file access functions and enhancements to VMS RMS 
performance monitoring functions. Although the benefits derived from 
these enhancements are readily apparent, functional details are transparent to 
most users. 
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Summary of Fields 


The symbolic offset, size, and a brief description of each XABITM field are 
presented in Table 11-1. 


Table 11-1 XABITM Fields 


Size 
Field Offset (Bytes) Description 
XAB$B_BLN' 1 Block length 
XAB$B_COD' 1 Type code 
XAB$L_ITEMLIST 4 Item list address 
XAB$B_MODE 4 Set/sense control 
XAB$L_NXT 4 Next XAB address 


This field is statically initialized by the $XABITM macro to identify the control block as an 
XABITM. 


XAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABITM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ITMLEN by the $XABITM macro. 


XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block 

as an XABITM. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_ITM by the $XABITM macro. 


XAB$L_ITEMLIST Field 


The item list address (ITEMLIST) field contains the symbolic address of the 
item list. 


XAB$L_MODE Field 


XABS$NXT Field 
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The item list mode (MODE) field specifies whether the items in the item list 


can be set by the program. It contains either the symbolic value XAB$K— 
SETMODE or the symbolic value XAB6K_SENSEMODE (default). 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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11.2 Network File Access Items 


This section lists and briefly describes the items that support network file 
access features. 


Network items are effectively ignored for local operations. Although the 
application program may include network items in the XAB chain for the 
related FAB, VMS RMS does not consider any of the network-specific fields 
during local processing. Nor does VMS RMS return remote file contents to 
the application program during local file processing. 


Table 11-2 lists the entries in the XABITM item list relating to network file 
access features together with the buffer size required to store the data and a 
brief functional description. Note that although the application program can 
sense all of the item values from the VMS RMS interface, it can set only the 
following item values: 


e XAB$_NET_BLOCK—COUNT 

¢ XAB$—_NET_EXTPROT 

¢ XAB$_NET_LINK_TIMEOUT 

¢ XAB$_NET_LINK_CACHE-ENABLE 
e XAB$_NET_DATA—CRC_ENABLE 
¢ XAB$—-UCHAR_CONTIGB 

e XAB$_UCHAR_ERASE 

e XAB$_UCHAR—_LOCKED 

e XAB$_UCHAR_NOBACKUP 

¢ XAB$_UCHAR—READCHECK 

e XAB$_UCHAR—WRITECHECK 


Table 11—2 XABITM Item List 


Required 
Buffer 
Item Size Description 
XAB$_NET_BUFFER_SIZE 4 bytes The size of the buffer allocated for DAP messages 


between the local and remote node is a negotiated 
value that is decided by DAP. This informational item 
returns the actual buffer size, in bytes, allocated for 
DAP messages. The buffer size is slightly larger than 
the limit specified for the records being transferred. 
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Table 11—2 (Cont.) XABITM Item List 


Item 


XAB$_NET_BLOCK _COUNT 


XAB$_NET_REMOTE_SYSTEM 


Required 
Buffer 
Size 


4 bytes 


4 bytes 


“MS-DOS is a trademark of Microsoft Corporation. 


Description 


This is the value in blocks that the local node wants 
to use for buffering messages between itself and the 
remote node. 


DAP tries to allocate this buffer space at the local 
node; however, if the maximum buffer size at the 
remote node is smaller, DAP allocates buffer space 
based on the smaller value. When the remote system 
incorporates VMS/FAL, it allows any size buffer up to 
32,767 bytes. 


The minimum buffer size for task-to-task network 
operations is 4096 bytes. 


This informational item returns the identity of the 
remote operating system using the symbolic constants 
listed in the following chart: 


Symbolic Constant Operating System 


XABS$K_RT 11 RT—11 
XABSK_RSTS RSTS/E 
XABS$K_RSX11S RSX-11S 
XAB$K_RSX11M RSX-11M 
XAB$K_RSX11D RSX-11D 
XABSK_IAS IAS 
XABSK_VAXVMS VMS 
XAB$K_—TOPS 10 TOPS-10 
XABS$K_TOPS20 TOPS-20 


XAB$K_RSX 1 1MP 


XAB$K_P_OS P/OS 
XABSK_VAXELN VAXELN 
XAB$K_MS_DOS MS-DOS™ 
XAB$K_ULTRIX_32  ULTRIX-32 


XAB$K_SNA_OS 


®igm is a registered trademark of International Business Machines, Inc. 
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RSX—-11M—PLUS 


SNA gateway to IBM® 


Table 11-2 (Cont.) XABITM Item List 


Item 


XAB$_NET_REMOTE_FILE_— 
SYSTEM 


XAB$_NET_EXTPROT 


Required 
Buffer 
Size 


4 bytes 


8 bytes 
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Description 


This informational item returns the identity of the 
remote file system using the symbolic constants listed 
in the following chart: 


Symbolic Constant File System 
XABS$K_RMS1 1 RMS—1 1 
XAB$K__RMS20 RMS-—20 
XAB$K_RMS32 RMS-32 
XAB$K_FCS11 FCS-—11 
XAB$K_RT11FS RT-11 
XAB$K_NO_FS No file system present 
XABS$K__TOPS20FS TOPS—20 
XAB$K_TOPS10FS TOPS—10 
XAB$K_RMS32S RMS-—32 subset (VAXELN) 
XAB$K_MS_DOSFS MS-DOS 


XAB$K_ULTRIX32_FS ULTRIX-—32 
XAB$K_SNA_FS SNA gateway to IBM 


This item permits the application program to specify 
or to sense the extended file protection that is likely 
to be mapped to a protection subset supported by the 
remote system. The application program implements 
extended file protection as part of either a Create or 
Close service by specifying the appropriate protection 
mask in the related subfield: 


Subfield Protection 


XABSW_SYSTEM_ACC System access 
XABSW_OWNER_ACC 
XAB$W_GROUP_ACC 
XAB$W_WORLD_ACC 


Owner access 
Group access 
World access 
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Table 11-2 (Cont.) XABITM Item List 


Item 


XAB$_NET_SYSCAP_LOCAL 


XAB$_NET_SYSCAP_REMOTE 


XAB$_NET_DAPVER_LOCAL 
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Required 


Buffer 
Size 


8 bytes 


8 bytes 


5 bytes 


Description 


Each of the protection mask fields provides the 
following mask values for further defining access: 


Mask Value 


XABSM_RED_ACC 
XABSM_WRT_ACC 
XABSM_EXE_ACC 
XAB$M_DLT_ACC 
XABSM_APP_ACC 
XAB$M_DIR_ACC 
XABSM_UPD_ACC 
XAB$M_CHG_ACC 


XABSM_EXT_ACC 


Protection Function 


Deny read access 
Deny write access 
Deny execute access 
Deny delete access 
Deny append access 
Deny directory access 
Deny update access 


Deny change protection 
access 


Deny extend access 


Note that not all systems support all of the protection 


mask fields. 


This informational item permits the applicatin program 
to read the network capabilities of the local system by 
returning symbolic bit vector values. See Table 11-3 

for a description of the network capabilities bit vectors 
used by the local and remote systems. 


This informational item permits the application program 
to read the network capabilities of the remote 

system by returning symbolic bit vector values. See 
Table 11-3 for a description of the network capabilities 
bit vectors used by the local and remote systems. 


This informational item returns the version of DAP on 
the local system using five symbolic bytes: 


Symbolic Byte 
XAB$B_VER_DAP 


XAB$B_VER_ECO 
XABS$B_VER_CUS 


XAB$B_VER_DSV 


XABS$B_VER_CSV 


Version Information 


DAP protocol version 
DAP protocol ECO level 


Customer modification level 
of DAP protocol; set to O by 
DIGITAL 


DIGITAL software version 
(release number) 


Customer software version 
number; set to O by 
DIGITAL 


Table 11—2 (Cont.) 


Item 


XAB$_NET_DAPVER_REMOTE 


XAB$_NET_LINK _TIMEOUT 


XAB$_NET_DATA_CRC_ENABLE 


XABS$_NET_LINK CACHE ENABLE 


XAB$_UCHAR_BADACL 
XAB$_UCHAR_BADBLOCK 
XAB$_UCHAR_CONTIG 
XAB$_UCHAR_CONTIGB 
XAB$_UCHAR_DIRECTORY 
XAB$_UCHAR_ERASE 
XAB$_UCHAR_LOCKED 
XABS_UCHAR_MARKDEL 
XAB$_UCHAR_NOBACKUP 
XAB$_UCHAR_READCHECK 
XAB$_UCHAR_SPOOL 
AB$_UCHAR_WRITECHECK 


XABITM Item List 


Required 
Buffer 
Size 


5 bytes 


4 bytes 


4 bytes 


4 bytes 


4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
4 bytes 
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11.2 Network File Access Items 


Description 


The DAP version is 07-01-00-05-00 for VMS 
Version 5.0. 


This informational item returns the version of DAP on 
the remote system using five symbolic bytes: 


Symbolic Byte Version Information 


XAB$B_VER_DAP 
XABSB_VER_ECO 
XABSB_VER_CUS 


DAP protocol version 
DAP protocol ECO level 


Customer modification level 
of DAP protocol; set to O by 
DIGITAL 


DIGITAL software version 
(release number) 


XAB$B_VER_DSV 


XAB$B_VER_CSV Customer software version 


number; set to O by 
DIGITAL 


This item permits the application program to set the 
timeout interval for logical link caching. The setting is 
passed as the number of seconds used to cache the 
logical link. A zero (O) setting enables caching until 
image rundown. The default interval is 30 seconds. 


This item allows the application program to enable 
cyclic redundancy checking at the DAP level. The 
symbolic value XAB$K_.ENABLE enables CRC checking 
at the DAP level (the default state); the symbolic value 
XAB$K_DISABLE disables CRC checking at the DAP 
level. 


This item is used to enable or to disable logical link 
caching. The symbolic value XABSK_ENABLE enables 
link caching (the default state); the symbolic value 
XAB$K_DISABLE disables link caching. 


File’s ACL is corrupt. 

File contains bad blocks. 

File is contiguous. 

Keep the file as contiguous as possible. 
File is a directory. 

Erase the file's contents before deleting it. 
File is deaccess-locked. 

File is marked for deletion. 

Do not back up the file. 

Verify read operations to the file. 

File is an intermediate spool file. 


Verify write operations to the file. 
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11.2 Network File Access Items 


The system capabilities supported by various DAP implementations are 
described using a vector of bits wherein a bit is set if the corresponding 
capability is supported. Any attempt to implement a feature at the local 
node that is not supported at the remote node is treated as a protocol 

error. Table 11-3 describes the bit vectors that VMS RMS uses to return 
the networking capabilities for both the local and remote nodes to the calling 
program. Capabilities supported by Version 5.0 of VMS are appropriately 
footnoted. 


Table 11-3 System Networking Capabilities 


Bit Value 


XAB$V_CAP_FILALL ' 
XAB$V_CAP_SEQORG' 
XAB$V_CAP_RELORG' 
XAB$V_CAP_EXTEND' 
XAB$V_CAP_SEOFIL' 
XAB$V_CAP_RANRRN' 
XAB$V_CAP_RANVBN' 
XAB$V_CAP_RANKEY ' 
XAB$V_CAP_RANRFA' 
XAB$V_CAP_IDXORG' 
XAB$V_CAP_SWMODE' 
XAB$V_CAP_APPEND' 
XAB$V_CAP_SUBMIT' 
XAB$V_CAP_MDS 
XAB$V_CAP_DISPLAY' 
XAB$V_CAP_MSGBLK ' 
XAB$V_CAP_UNRBLK 
XAB$V_CAP_BIGBLK ' 


XAB$V_CAP_DAPCRC' 
XAB$V-CAP_KEY XAB' 
XAB$V_CAP_ALLXAB' 
XAB$V_CAP_SUMXAB' 


Capability 


Allocation of space at file creation 
Sequential file organization 

Relative file organization 

Manual file extension 

Sequential file access (file transfer mode) 
Random access by relative record number 
Random access by virtual block number 
Random access by key value 

Random access by record file address 
Multikeyed indexed file organization 
Dynamic switching of access modes 
Records appended to end of file 
Command file submission/execution 
Multiple data streams for each file 

Display of file attributes on request 
Blocking of DAP messages up to response (less than 256 bytes) 
Unrestricted blocking of DAP messages 


Blocking of DAP messages up to response (greater than or equal to 256 
bytes) 


DAP message CRC checksum 
Key definition XAB message 
Allocation XAB message 


Summary XAB message 


XAB$V_CAP_DIRECTORY!' Directory list operation 


‘Supported for VMS Version 5.0. 
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11.2 Network File Access Items 


Table 11-3 (Cont.) System Networking Capabilities 


Bit Value 


Capability 





XAB$V_CAP_TIMXAB' 
XAB$V_CAP_PROXAB' 
XAB$V_CAP_FOPSPL' 
XAB$V_CAP_FOPSCF' 
XAB$V_CAP_FOPDLT ' 
XAB$V_CAP_SEQRAC' 
XAB$V_CAP_BITOPT 
XAB$V_CAP_WARNING 
XAB$V_CAP_RENAME! 
XAB$V_CAP_WILDCARD' 
XAB$V_CAP_GNGOPT 
XAB$V_CAP_NAMMSG' 
XAB$V_CAP_SEGMSG 
XAB$V_CAP_CHGATTCLS 
XAB$V_CAP_CHGTIMCLS' 
XAB$V_CAP_CHGPROCLS' 
XAB$V_CAP_CHGNAMCLS 
XAB$V_CAP_MODATTCRE 
XAB$V_CAP_NAM3PART 


XAB$V_CAP_CHGATTREN 
XAB$V_CAP_CHGTIMREN 

XAB$V_CAP_CHGPROREN 
XAB$V_CAP_CTLBLKCNT' 
XAB$V_CAP_OCTALVER 


Date and time XAB message 

File protection XAB message 

Spool file on Close FOP option 

Submit command file on Close FOP option 

Delete file on Close FOP option 

Sequential record access 

Bit count option in the FLAGS field 

Warning status message and error recovery message exchange 
File rename operation 

Wildcard operations (excluding directory) 

Go/Nogo option in the ACCOPT field 

Name message 

Segmented DAP messages 

Changing file attributes on Close using ATT message 
Changing file attributes on Close using TIM message 
Changing file attributes on Close using PRO message 
Changing file attributes on Close using NAM message 
Modified attributes returned when file is created 


Three-part name message format in DISPLAY field of both Access and 
Control messages 


Changing file attributes on Rename using ATT message 
Changing file attributes on Rename using TIM message 
Changing file attributes on Rename using PRO message 
BLKCNT field in Control message 

Octal version numbers only in file specifications 





‘Supported for VMS Version 5.0. 





VMS RMS Performance Monitoring 


This section describes the implementation of VMS RMS performance 
monitoring from the VMS RMS interface using a XABITM. 


To explicitly obtain VMS RMS performance statistics for a file through the 
VMS RMS interface, the application program enables the statistics function 
using the XAB$_STAT_ENABLE item. This item may contain either the . a 
symbolic value XAB$K_DISABLE (default) or XAB$K_ENABLE. The XAB$.. — 
STAT_ENABLE item may be used on $CREATE to initially mark the file 
for statistics gathering, or it may be used in $DISPLAY (or implied display) 
operations to sense the statistics monitoring state. 


11-9 


Item List XAB (XABITM) 
11.3 VMS RMS Performance Monitoring 


11-10 


You can enable statistics for an existing file from the DCL interface using 
the SET FILE command. See the VMS DCL Dictionary for details. For 
details about using the Monitor Utility for gathering VMS RMS performance 
statistics, see the VMS Monitor Utility Manual. 


Example 11-1 illustrates the use of XABITM to enable statistics monitoring: 
Example 11—1_ Using XABITM to Enable VMS RMS Statistics 


ITEMLIST : BLOCK [ITM$S_ITEM+4, BYTE] 
INITIAL( REP (ITM$S_ITEM+4) OF (0) ), 


ITEM_XAB : $XABITM( mode = SETMODE, 
itemlist = ITEMLIST ), 


ITEM_BUFFER : LONG INITIAL ( XAB$K_ENABLE) ; 
FILE_FAB : $FAB( 


XAB = ITEM_XAB, 


3 
ITEMLIST[ITM$W_ITMCOD] = XAB$_STAT_ENABLE; 
ITEMLIST[ITM$W_BUFSIZ] = 4; 
ITEMLIST[ITM$L_BUFADR] = ITEM_BUFFER; 


$CREATE( fab = FILE_FAB ); 


12 Journaling XAB (XABJNL) 


The journaling XAB ($XABJNL) control block supports file journaling 
operations. See the VAX RMS Journaling Manual for details. 
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13 Key Definition XAB (XABKEY) 


You must provide a key definition XAB (XABKEY) for each key in an indexed 
file in order to define the key’s characteristics. Before you create an indexed 
file, you must establish the contents of the XABKEY fields for the primary key 
and for each alternate key. 


When you invoke an Open or Display service for an existing indexed file, you 
can use XABKEYs if you want to provide your program with one or more 

of the key definitions specified when the file was created. Alternatively, the 
summary XAB (see Chapter 17) provides the number of keys, number of 
allocated areas, and the prolog version assigned to the file. 





13.1 Summary of Fields 


Table 13-1 lists the symbolic offset, size, FDL equivalent, and a brief 
description of each XABKEY field. 


Table 13-1 XABKEY Fields 


Field Offset home FDL Equivalent Description 

XAB$B_BLN' 1 None Block length 

XAB$B_COD'! 1 None Type code 

XAB$L_COLNAM 4 None Collating sequence name 

XAB$L_COLSIZ 4 None Collating sequence table size 

XAB$L_COLTBL 4 COLLATING._SEQUENCE Collating sequence table address 

XABS$B_DAN 1 KEY DATA_AREA Data bucket area number 

XAB$B_DBS? 1 None Data bucket size 

XABSW_DFL 2 KEY DATA_FILL Data bucket fill size 

XAB$B_DTP 1 KEY TYPE? Data type of the key 

XAB$L_DVB? 4 None First data bucket virtual block number 

XAB$B_FLG 1 KEY? Key options flag 

XAB$B_IAN 1 KEY INDEX_AREA Index bucket area number 

XAB$B_IBS? 1 None Index bucket size 

XABSW_IFL 2 KEY INDEX _FILL Index bucket file size 

XAB$L_KNM 4 KEY NAME Key name buffer address 

XAB$B_LAN 1 KEY LEVEL1_INDEX _ Lowest level of index area number 
AREA 

XAB$B_LVL? 1 None Level of root bucket 





'This field is statically initialized by the $XABKEY macro to identify this control block as an XABKEY. . 
2This field cannot be initialized by the $XABKEY macro. 


3This field contains options; corresponding FDL equivalents are listed in the description of the field. 
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Table 13-1 (Cont.) 


Field Offset 
XAB$W_MRL? 
XAB$B_NSG? 
XAB$B_NUL 
XAB$L_NXT 
XAB$W__POSn 


XAB$B_PROLOG 
XAB$B_REF* 
XAB$L_RVB? 
XAB$B_SIZn 


XAB$B_TKS? 


XABKEY Fields 


Size 

(Bytes) FDL Equivalent Description 

2 None Minimum record length 

1 None Number of key segments 

1 KEY NULL_VALUE Null key value 

4 None Next XAB address 

2 KEY POSITION and Key position, XAB$W_POSO to 


SEGn_POSITION XAB$W_POS7 

KEY PROLOG Prolog level 

KEY n Key of reference 

None Root bucket virtual block number 
KEY LENGTH and Key size XAB$B_SIZO to 
SEGn_LENGTH XAB$B_SIZ7 

None Total key field size 


2This field cannot be initialized by the $XABKEY macro. 
4For BLISS-32, this field is designated XAB$B_KREF. 


Each XABKEY field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $XABKEY macro and the $XABKEY_STORE 
macro are defined in Appendix B. 


13.2  XABS$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABKEY, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. The $XABKEY macro initializes the XAB$B_BLN 
field to the symbolic value XAB$C_KEYLEN. 


13.3. XABSB_COD Field 


The type code (COD) field is a static field that identifies this control block as 
an XABKEY. Once set, this field must not be altered unless the control block 
is no longer needed. The $XABKEY macro initializes the XAB$B_COD field 
to the symbolic value XAB$C_KEY. 
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13.4 XABSL_COLNAM Field 


When you invoke the Display service, VMS RMS uses this field to return a 
pointer to a memory buffer containing the name of the collating sequence for 
this key. 


The name buffer is in the form of an ASCII counted string where the first 
byte indicates the length of the name and the remaining bytes are the ASCII 
representation of the name itself. The maximum length of the buffer is 32 
bytes, one byte for the count and 31 bytes for the name. 


13.5 XAB$L_COLSIZ Field 


When you invoke the the Display service, VMS RMS returns the size, in 
bytes, of the collating sequence used with this key to this field. 


13.6 XABSL_COLTBL Field 


DST_KEYO: 
$XABKEY 


Note: 


VMS RMS provides you with a way to use alternative (non-ASCII) collating 
sequences with indexed file keys. You can define a collating sequence for 
each key of reference, yielding, for example, a file sorted in German by one 
key, French by another key, and so forth. 


This feature is based on the National Character Set Utility, which permits you 
to define alternative collating sequences for special characters and to establish 
and maintain a library of collating sequences. This eliminates having to 
redefine an alternative collating sequence when the application requires it. 
See the VMS National Character Set Utility Manual for details. 


Key compression and index compression are not permitted with collating 
keys. 


To access an alternative collating sequence for a key, enter the symbolic 
address of the appropriate collating table in the XAB$L_COLTBL field. For 
example, you might enter the following: 


COLTBL=FRENCH, - ;symbolic address of French collating table 


VMS RMS responds by storing the specified collating table in the initial blocks 
of the indexed file immediately following the area descriptors. Collating 
tables are typically about one block long. 


When you invoke the Display or the Open service, VMS RMS returns the 
address of the collating table in this field. 


This field corresponds to the FDL attribute COLLATING_SEQUENCE. 
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13.7. XAB$B_DAN Field 


The data bucket area number (DAN) field contains a numeric value that 
identifies the area where the data buckets for this key reside. The number 
reflects the value in the XAB$B_AID field of the XABALL for this XAB chain. 
The numeric value may range from 0 through 254, but the default is 0; that 
is, area 0. 


When you create a new indexed file or when you use allocation XABs to 
define areas (see Chapter 8), you must specify a value for this field to identify 
the file area where the data buckets are to reside. 


When an XABKEY describes the primary key, the data level of the index 
consists of buckets that contain the actual data records of the file. However, 
when the key definition describes an alternate key, the data level of the index 
consists of buckets in which VMS RMS maintains pointers to the actual data 
records. 


The XAB$B_DAN field corresponds to the FDL attribute KEY DATA_AREA. 


13.8 XABS$B_DBS Field 


After an Open or Display service, the data bucket size (DBS) field contains the 
size of the data level (level 0) buckets, in virtual blocks, for the key described 
by the XAB. 


13.9 XABSW_DFL Field 
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The data bucket fill size (DFL) field contains a numeric value that indicates 
the maximum number of bytes (of data) in a data bucket. The largest possible 
fill size is the bucket size, in blocks, multiplied by 512. The default value is 
0, which is interpreted by VMS RMS as the maximum available space (that 
is, no unused space). If the specified size is not 0, but is less than one-half of 
the bucket size (in bytes), then the fill size used is one-half of the bucket size. 


When you create an indexed file, you use this field to specify the number 

of bytes of data you want in each data level bucket. If you specify a value 
that is less than the actual bucket size, the data buckets contain some amount 
of free space. At run time, VMS RMS uses the fill size specified when the 
file was created only if the RAB$L_ROP (record-processing options) field 
RAB$V_LOA option is specified in the RAB; otherwise, VMS RMS fills the 
buckets. 


When an XABKEY describes the primary key, the XABSW_DFL field describes 
the space in the buckets containing actual user data records. When the 
XABKEY describes an alternate key, the XABS$W_DFL field describes the 
space in the buckets containing pointers to the user data records. 


It is advantageous to use the XAB$W_DFL field if you expect to execute 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of records (bucket 
splitting) by specifying less than the maximum bucket fill size when you 
create the file. To use the free space reserved in the buckets, programs that 
execute Put or Update services on the file should not specify the RAB$L_— 
ROP field RAB$V_LOA option. 
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This field corresponds to the FDL attribute KEY DATA_FILL (which is 
expressed as a percentage). 





13.10 XABSB_DTP Field 


The XAB$B_DTP field specifies the key data type and the key sort order, 
ascending or descending. 


In this keyword value field, each key data type option is defined by a 
symbolic value. If the key sort order is descending, the letter D is prefixed to 
the symbolic value; if the sort order is ascending, the prefix is omitted. For 
example, a XAB$B_DTP field having the value XAB$C_DBN2 is an unsigned, 
2-byte binary number that is sorted in descending order. On the other hand, 
a XAB$B_DTP field having the value XAB$C_BN2 is an unsigned, 2-byte 
binary number that is sorted in ascending order. 


Only one option can be specified. It is identified by a symbolic constant 
value; for example, the STG (string) option has the constant value XAB$C_ 
STG. | 


The options for the XAB$B_DTP field are listed in the following chart: 


Keyword Data Type Sort Order 
XAB$C_BN2 Unsigned 2-byte binary Ascending 
XAB$C_DBN2 Unsigned 2-byte binary Descending 
XAB$C_BN4 Unsigned 4-byte binary Ascending 
XAB$C_DBN4 Unsigned 4-byte binary Descending 
XAB$C_BN8 Unsigned 8-byte binary Ascending 
XAB$C_DBN8 Unsigned 8-byte binary Descending 
XAB$C_IN2 Signed 2-byte integer Ascending 
XAB$C_DIN2 Signed 2-byte integer Descending 
XAB$C_IN4 Signed 4-byte integer Ascending 
XAB$C_DIN4 Signed 4-byte integer Descending 
XAB$C_IN8 Signed 8-byte integer Ascending 
XAB$C_DIN8 Signed 8-byte integer Descending 
XAB$C_COL Collating key Ascending 
XAB$C_DCOL Collating key Descending 
XAB$C_PAC Packed decimal string Ascending 
XAB$C_DPAC Packed decimal string Descending 
XAB$C_STG' Left-justified string of Ascending 
unsigned 8-bit bytes 
XAB$C_DSTG Left-justified string of Descending 


unsigned 8-bit bytes 


'This is the default value. 


The string data type may consist of from one to eight detached key field 
segments that collectively make up the key. For more information about 
segmented keys, see the descriptions of the XAB$W_POSO through XABSW_ 
POS7 field and the XAB$B_SIZO through XAB$B_SIZ7 field. 


13-5 


Key Definition XAB (XABKEY) 
13.10 XAB$B_DTP Field 


Integer, binary, and packed decimal key fields must be a contiguous set of 
bytes. 


The null value (that is, the XAB$V_NUL option in the XAB$B_FLG field is 
set) for the integer, binary, collating and packed decimal data types is 0, and 
the XAB$B_NUL field is ignored (see XAB$B_FLG and XAB$B_NUL). 


The formats of the binary and integer key field data types are presented 


below. 

Key Type Format 

XABSC_BN2 LSB at A, MSB at A+1 
XAB$C_DBN2 LSB at A, MSB at A+1 
XAB$C_BN4 LSB at A, MSB at A+3 
XAB$C_DBN4 LSB at A, MSB at A+3 
XABS$C_BN8 LSB at A, MSB at A+7 
XAB$C_DBN8 LSB at A, MSB at A+7 
XAB$C_IN2 LSB at A, MSB and sign at A+1 
XAB$C_DIN2 LSB at A, MSB and sign at A+1 
XABS$C_IN4 LSB at A, MSB and sign at A+3 
XAB$C_IN4 LSB at A, MSB and sign at A+3 
XAB$C_IN8 LSB at A, MSB and sign at A+7 
XAB$C_DIN8 LSB at A, MSB and sign at A+7 


The collating key data types are used in conjunction with collating sequences 
located in the indexed file prolog. Collating sequences are used with 
multinational characters and are specified for each key. Note that key 
compression and index compression are not permitted with collating keys. 


A packed decimal string is a contiguous sequence of bytes specified by two 
attributes: the address (A) of the first byte of the string and a length (L) that 
is the number of digits in the packed decimal. The bytes of a packed decimal 
are divided into two 4-bit fields that must contain decimal digits, except for 
the first four bits (0 through 3) of the last (highest addressed) byte, which 
must contain a sign. The representation for the digits and signs is shown 
below. 


Digit or Sign Decimal Value Hexadecimal Value 


N DOO BP WDY = 
N © oO fF WHY = O 
N Oo BP WH = 
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Digit or Sign Decimal Value Hexadecimal Value 
8 8 8 

9 9 9 

+ 10, 12, 14, or 15 A, C, E, or F 

- 11 or 13 Bor D 


The preferred sign representation is 12 for plus (+) and 13 for minus (-). 
The length (L) is the number of digits in the packed decimal string (not 
counting the sign) and must be in the range 0 through 31. When the 

number of digits is even, an extra 0 digit must appear in the last four bits 

(4 through 7) of the first byte. Again the length in bytes of the packed 
decimal is L/2 + 1. The value of a zero-length packed decimal is 0; it contains 
only the sign byte, which also includes the extra 0 digit. 


The address, A, of the packed decimal specifies the byte containing the most 
significant digit in its high order. Digits of decreasing significance are assigned 
to increasing byte addresses and from high to low within a byte. Thus, +123 
has length 3 and is represented as follows: 


ZK-873-82 


Similarly, -12 has length 2 and is represented as follows: 


ZK-874-82 


This field corresponds to the FDL attribute KEY TYPE. 


13.11 XABSL_DVB Field 


After an Open or Display service, the DVB field contains the starting virtual 
block number of the first data level bucket for the key described by the XAB. 
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13.12 XABS$B_FLG Field 
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The key options flag (FLG) field specifies the following conditions: 
e¢ Whether duplicate keys are permitted in the file 

e Whether a key value can change 

¢ Whether data is compressed 


e Whether string key options apply 


Primary key values cannot change, but alternate key values may change, 
depending on application requirements. Primary and alternate keys may be 
duplicated depending on the key field and the application. An alternate key 
field is more likely than a primary key field to use duplicates. 


This field is a binary options field where each key characteristic has a 
corresponding bit assignment. Multiple key characteristics can be associated 
with each key (multiple bits can be set). Each option in the field has its own 
symbolic offset and mask value. For example, the CHG key characteristic has 
a symbolic offset of XAB$V_CHG and a mask value of XAB{M_CHG. 


When you create an indexed file and are defining a string key, you can 
optionally specify the XAB$V_IDX_NCMPR, XAB$V_KEY_NCMPR, and 
XAB$V_NUL options. 


These are the options for the XAB$B_FLG field: 


Options 


XAB$V_CHG 


The key value within the record in the file can be changed by a program 
during an Update service. This option can be specified only for alternate 
keys. 


This option corresponds to the FDL attribute KEY CHANGES. 


XAB$V_DAT_NCMPR 


Do not compress data. This option can be specified to override compression 
of data for Prolog 3 files for the primary key; that is, when XAB$_REF is 0. 


This option corresponds to the FDL attribute KEY DATA_RECORD_ 
COMPRESSION. 


This option is not supported for DECnet operations; it is ignored. 


XAB$V_DUP 
The key value within the record in the file may have the same key value as 
another record (or other records) within the file. 


This option corresponds to the FDL attribute KEY DUPLICATES. 
XAB$V_IDX_NCMPR 


Do not compress index. This option can be specified to override compression 
of keys in the index for Prolog 3 files. This option is only valid if a string key 
is being defined. 


This option corresponds to the FDL attribute KEY INDEX_COMPRESSION 
and it is not supported for DECnet operations. . 
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XAB$V_KEY_NCMPR 


Do not compress key. This option can be specified to override compression of 
each key for Prolog 3 files. For a primary key (XAB$_REF is 0), the primary 
keys at the data level are not compressed; for each alternate key (XAB$_REF 
is greater than 0), the secondary index data records (SIDRs) that point to the 
data record location are not compressed. This option is only valid if a string 
key is being defined. 


This option corresponds to the FDL attribute KEY DATA_KEY_ 
COMPRESSION and it is not supported for DECnet operations. 


XAB$V_NUL 


When set, this bit refers VMS RMS to the XAB$B_NUL field to determine 
whether or not you have defined a null character for removing records from 
the related alternate index. This option can be specified only for alternate key 
indexes using string type keys. 


The defaults and combinations of allowing changeable key values (XAB$V_ 
CHG option) and duplicate key values (XAB$V_DUP option) depend on 
whether a primary or alternate key is being defined by this XABKEY. The 
allowed combinations and defaults for duplicate and changeable key values 
are described below. 


Combinations Primary Key Alternate Key 
XAB$V_CHG and XAB$V_DUP both set Error Allowed 
XAB$V_CHG set, XAB$V_DUP clear Error Allowed 
XAB$V_CHG clear, XAB$V_DUP set Allowed Allowed 
XAB$V_CHG and XAB$V_DUP both clear Default Default 


By default, duplicate keys are not allowed for the primary key and its value 
cannot change. 


If the XABKEY control block is not initialized by the $XABKEY macro, then 

the defaults for alternate keys are the same as for primary keys and null key 
values are not used. However, if the XABKEY control block is initialized by 

the $XABKEY macro, the following defaults apply to alternate keys: 


¢ Duplicate key values are allowed. 
e Key values can change. 


¢ Null key values are not allowed. 


These defaults are applied only if the entire XAB$B_FLG field is defaulted. 


Note that VMS RMS supports alternate indexes that prohibit duplicate key 
values but do allow key values to change for Update services. Older versions 
of RMS-11 (in contrast to VMS RMS) do not allow this particular combination 
of attributes for alternate indexes. This factor should be considered when you 
create files with VMS RMS that may also be processed by RMS-11. 


This option corresponds to the FDL attribute KEY NULL_KEY. 
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13.13 XAB$B_IAN Field 


13.14 XABS$B_IBS Field 


The index bucket area number (IAN) field contains a numeric value in the 
range 0 through 254, representing an area identification number contained in 
the XAB$B_AID field of an XABALL present in the same chain. The default 
is 0 (that is, area 0). 


When you create an indexed file, you use this argument to specify the area of 
the file that the index buckets are to reside in only when both of the following 
are true: 


e You are creating a new indexed file. 


e You are using allocation XABs to define areas. 


When the XABKEY describes the primary key, the index level of the index 
consists of all levels of the tree-structured primary index down to and 
including the level containing pointers to the user data records themselves. 
However, when the key definition describes an alternate key, the index 

level of the index comprises all levels of the tree-structured alternate index 
down to, but not including, the level containing buckets in which VMS RMS 
maintains pointer arrays describing the user data records. For directions about 
how to place the lowest level of the index in a location separate from the 
higher levels, see the description of the XAB$B_LAN field. 


This field corresponds to the FDL attribute KEY INDEX_AREA. 


After an Open or Display service, the index bucket size (IBS) field contains 
the size of the index level (level 1 to n buckets, in virtual blocks, for the key 
described by the XAB). 





13.15 XABS$W_IFL Field 
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The index bucket fill size (IFL) field contains a numeric value representing 
the maximum number of bytes in an index bucket. The maximum possible 
fill size is the bucket size, in blocks, multiplied by 512. The default value 

is 0, which is interpreted by VMS RMS as meaning the maximum available 
space (that is, no unused space). If the specified size is not 0, but is less than 
one-half of the bucket size (in bytes) then the fill size used is one-half of the 
bucket size. 


When you create an indexed file, you use this argument to specify the 
number of bytes you want in each index bucket. If you specify less than 
the total possible bucket size, you indicate that the index buckets are to 
contain some amount of free space. At run time, VMS RMS uses the fill size 
specified at creation time if the LOA option is specified in the RAB$L_ROP 
(record-processing options) field of the RAB; otherwise, VMS RMS fills the 
buckets. 


When an XABKEY describes the primary key, the XAB$W_IFL field describes 
the space in the buckets in all levels of the primary index down to and 
including the level containing pointers to the user data records. When an 
XABKEY describes an alternate key, the XAB$W_IFL field describes the space 
in the buckets in all levels of the alternate index down to, but not including, 
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the level containing buckets in which VMS RMS maintains pointer arrays 
describing the user data records. 


It is advantageous to use the XAB$W_IFL field if you expect to perform 
numerous random Put and Update services on the file after it has been 
initially populated. You can minimize the movement of index records (bucket 
splitting) by specifying less than the maximum bucket fill size when a file is 
created. To use the free space thereby reserved in the buckets, programs that 
invoke the Put or Update services for writing to the file should not specify 
the RAB$L_ROP field RAB$V_LOA option. 


This field corresponds to the FDL attribute KEY INDEX —FILL (which is 
expressed as a percentage). 





13.16 XABSL_KNM Field 


The key name buffer address (KNM) field contains the symbolic address of a 
buffer that is available for assigning a user-specified name to the key being 
defined. The name buffer must be at least 32 bytes in length and you may 
use any 32-character string you choose to name the key field. 


If the default value is taken (0), VMS RMS assumes no name is to be 
assigned to the key. VMS RMS does not use this string but retains it in the 
file as part of the key definition information for documentation purposes. 


This field corresponds to the FDL attribute KEY NAME. 





13.17 XABS$B_LAN Field 


The lowest level of index area number (LAN) field contains a numeric value 
(0 through 254) representing an area identification number contained in the 
XAB$B_AID field of an XABALL present in the same XAB chain. If the 
XAB$B_LAN field is not specified (that is, if the value is 0), the value in the 
XAB$B_IAN field is used as a default; in other words, the lowest level of the 
index occupies the same area of the file as the remainder of the index. 


This field permits you to separate the lowest level (level 1) of the index from 
all higher levels (levels 2+) of the index in an indexed file; you can use the 
XAB$B_LAN field to specify an area of the index wherein the lowest level of 
the index resides, separate from the area (or areas) specified by the XAB$B_ 
IAN field (wherein all other levels of the index reside). See XAB$B_IAN for 
additional information. 


You can specify the XAB$B_LAN field only when both of the following 
conditions exist: 


e¢ You are creating a new indexed file. 


e You are using allocation XABs to define areas. 


Note that the area specified by the XAB$B_LAN field must have the same 
bucket size as the area specified by the XAB$B_IAN field. 


This field corresponds to the FDL attribute KEY LEVEL1_INDEX_AREA. 
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XABS$B_LVL Field 


Following an Open or Display service, the level of root bucket (LVL) field 
contains the level of the root bucket for the key described by the XAB. 


XABSW_MRL Field 


Following an Open or Display service, the minimum record length (MRL) 
field contains the minimum record length (in bytes) needed to contain the key 
field for the key described by the XAB. 


If the key described by the XAB is the primary key (XAB$_REF is 0), then a 
record must be equal to or greater than the minimum record length returned 
in XABSW_MRL to be inserted or updated in the file. 


If the key described by the XAB is an alternate key (XAB$_REF is greater 
than 0), then a record must be equal to or greater than the minimum record 
length returned in the XABSW_MRL field to be recorded in the associated 
index for that alternate key. 


XABS$B_NSG Field 


Following an Open or Display service, the number of key segments (NSG) 
field contains the number of key segments that make up the key field for the 
key described by the XAB (see the XAB$W_POSO through XABSW_POS7 
field). 


XABSB_NUL Field 


Normally, VMS RMS updates all indexes to reflect the values in the 
corresponding key fields of the records written to an indexed file. The 
XAB$B_NUL field permits you to instruct VMS RMS not to make an entry 
in an alternate index if a record being entered in an indexed file contains a 
specified null alternate key value. To specify the XAB$B_NUL field, three 
conditions must be satisfied: 


e The XABKEY must define an alternate key. 


e The XAB$B_FLG field XAB$V_NUL option must be set when you create 
the file (see XAB$B_FLG). 


e¢ The key data type must be string. 
You can use any ASCII character in the null (NUL) field if you are defining a 


string-type alternate key. The default null value for string-type alternate keys 
is 0 and nonstring keys always use 0 for the null value. 


This field corresponds to the FDL attribute KEY NULL_VALUE. 





13.22 XAB$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 
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13.23 XAB$SW_POSO Through XAB$W_POS7 Field 


There are two types of keys, simple keys and segmented keys. 


A simple key is made up of one or more contiguous bytes and it may be used 
with any data type, including the string data type. For simple keys, the first 
byte of the key position field contains a numeric variable whose value relative 
to 0 defines the starting position of the key. The remaining bytes contain 
Zeros. 


Segmented keys include two through eight strings of key data (segments) and 
can only be used with string data type key fields. The key segments need 
not be contiguous nor must they be in a particular order. Key segments may 
overlap except for primary keys used with Prolog 3 files. If your application 
requires overlapping key segments in a Prolog 3 file, consider using an 
alternate segmented key. If you must have a primary key with overlapping 
segments, VMS RMS requires you to use either a Prolog 2 or Prolog 1 
structure (which it automatically assigns if the XAB$B_PROLOG field is not 
specified). 


For segmented keys, the first word of the key position field specifies the 
starting position of the first segment and each succeeding byte specifies the 
starting position of one of the remaining segments. When processing records 
that contain segmented keys, VMS RMS regards a segmented key field as a 
single, logically contiguous string beginning with the first segment and ending 
with the last. 


You should note that the XABSW_POSO through XAB$W_POS7 and the 
XAB$B_SIZO through XAB$B_SIZ7 (key size) fields must define the same 
number of key position values and key. size values. 


This field corresponds to the FDL attributes KEY POSITION and SEGn_— 
LENGTH. 


13.24 XAB$B_PROLOG Field 


The prolog (PROLOG) field defines the version or structure level of the file 
index. It contains a numeric value from 0 through 3. 


The XAB$B_PROLOG field is input to the Create service, and it is returned 
by the Display and Open services. 


This field must only be used to define a primary key. 


Prolog 3 is the default prolog level, unless the primary key contains 
overlapping segments. VMS RMS examines the key characteristics and 
determines the correct prolog structure to apply to the file. If the XAB$B_ 
PROLOG field is not specified (that is, if the value is 0), the process default 
prolog level is examined, then the system default prolog level is used. These 
default values are set by the DCL command SET RMS_DEFAULT/PROLOG. 


You should not specify a prolog level 1 because VMS RMS decides whether 
a Prolog 1 or Prolog 2 file should be created, depending on the key type 
defined for the file. If you want to select a prolog level other than Prolog 3, 
you should select either 0 or 2. 


For more detailed information regarding the options for selecting a specific 
prolog level, see the description of the Create service in Part III. 
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This field corresponds to the FDL attribute KEY PROLOG and it is not 
supported for DECnet operations; the default prolog in effect at the remote 
node is used. 





13.25 XAB$B_REF Field 


Note: 


The key of reference (REF) field defines a key as either the primary key or 
some alternate key. 


For BLISS-32, this field is designated XAB$B_KREF. 


This field contains a numeric value in the range 0 through 254. A value of 0 
indicates that this is the primary key; a value of 1 indicates the first alternate 
key; a value of 2 indicates the second alternate key, and so on. The order of 
the XABKEYs is irrelevant. 


Note that VMS RMS can process an indexed file with 255 defined keys; each 
defined key field, however, has an associated cost in processing and I/O 
time. The time required to build and maintain the index for the key field 
and the disk storage required to contain the index for each key field should 
be considered when you decide whether the field should be an alternate key 
field. A file with six to eight defined keys (the primary key and five to seven 
alternate keys) should be considered as a maximum; a file with two or three 
defined keys is typical. 


This field corresponds to the FDL attribute KEY n where n is the number of 
the key being defined). 


13.26 XABSL_RVB Field 


13.27 XAB$B_SIZO Th 


13-14 


After an Open or Display service, the root index bucket virtual block number 
(RVB) field contains the virtual block number for the root bucket of the index 
for the key described by the XAB. 


rough XAB$B_SIZ7 Field 


The key size (SIZ) field defines the length of the key field within each record. 
This field contains a numeric value representing the length, in bytes, of the 
key within the record. Up to eight values can be assigned; maximum values 
depend on the type of key. 


The XAB$B_SIZO through XAB$B_SIZ7 field defines the length (in bytes) 
of the key whose starting position is defined in the key position field of the 
XAB. Two types of keys can be defined: simple and segmented (see the 
XAB$W_POSO through XAB$W_POS7 field). 


For a simple key, the XAB$B_SIZO through XAB$B_SIZ7 field contains only 
one key size value (in XAB$B_SIZO). 


For a segmented key, the XAB$B_SIZO through XAB$B_SIZ7 field contains 

a key size value for each segment of the key. You should note that the 
XAB$B_SIZO through XAB$B_SIZ7 field and the XAB$W_POSO through 
XAB$W_POS7 field must contain the same number of key size values and 
key position values. VMS RMS associates the first key position value with the 
first key size value to define the location and length of the first segment of a 
segmented key, and so forth. 
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When the data type of the key is string, the total size (sum of all sizes) of the 
key must be less than 256 bytes. 


When the data type of the key is 2-byte integer or 2-byte binary, XAB$B_ 
SIZO must equal 2 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If 
the size is 0, it defaults to 2. 


When the data type of the key is 4-byte integer or 4-byte binary, XAB$B_ 
SIZO must equal 4 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If 
the size is 0, it defaults to 4. 


When the data type of the key is 8-byte integer or 8-byte binary, XAB$B_ 
SIZO must equal 8 and XAB$B_SIZ1 through XAB$B_SIZ7 must contain 0. If 
the size is 0, it defaults to 8. 


When the data type of the key is packed decimal, the size specified by 
XAB$B_SIZO must be from 1 through 16, and XAB$B_SIZ1 through XAB$B_ 
SIZ7 must contain 0. | 


This field corresponds to the FDL attribute KEY LENGTH or KEY SEGn_ 
LENGTH where n is the number of the segment being defined. 





13.28 XABS$B_TKS Field 


After an Open or Display service, the total key size (TKS) field contains the 
total key size (the sum (in bytes) of XAB$B_SIZO through XAB$B_SIZ7) for 
the key described by the XAB. 
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Protection XAB (XABPRO) 


The protection XAB (XABPRO) specifies the ownership, accessibility and 
protection for a file. Although an XABPRO is typically used as input to 
the Create service, you can use it to change the protection of a file when 
you execute the Close service if you have write access to the file and have 
accessed the file for some type of modification (Put, Update, Delete, or 
Truncate). 





Summary of Fields 


Table 14—1 


Field Offset 


XABS$L_ACLBUF 
XAB$L_ACLCTX 
XAB$SW_ACLLEN 


XAB$W_ACLSIZ 
XAB$L_ACLSTS 
XAB$B_BLN' 
XAB$B_COD' 
XAB$W_GRP? 
XAB$W_MBM? 
XAB$B_MTACC 
XAB$L_NXT 
XAB$W_PRO 


XAB$B_PROT_OPT 
XABSL_UIC 


The symbolic offset, size, FDL equivalent, and a brief description of each 
XABPRO field are presented in Table 14-1. 


XABPRO Fields 


Size 
(Bytes) 
4 

4 

2 


NO PB Pe NM NY | — FN 


FDL Equivalent 


None 
None 


None 


None 

None 

None 

None 

FILE OWNER 

FILE OWNER 

FILE MT_PROTECTION 
None 

FILE PROTECTION 


None 
FILE OWNER 


Description 


Address of buffer that contains ACL 
ACL positioning context 


Receives the length of an ACL during 
an Open or Display service 


Length of buffer containing binary ACEs 
System error status for ACL processing 
Block length 

Type code 

Group number of file owner 

Member number of file owner 

Magnetic tape accessibility 

Next XAB address 


File protection; contains four separate 
fields denoting protection for system, 
owner, group, and world 


File protection options 


User identification code; contains both 
the group and member fields 


'This field is statically initialized by the $XABPRO macro to identify this control block as an XABPRO. 
2This field cannot be initialized by the $XABPRO macro. 
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Each XABPRO field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $XABPRO macro and the $XABPRO_ 
STORE macro are defined in Appendix B. 


14.2  XABSL_ACLBUF Field 


The ACL buffer field (ACLBUF) stores the address of a buffer area that 
contains an access control list (ACL) for this file. The ACL buffer contains one 
or more access control entries (ACE) in binary format. The system processes 
the ACL until it encounters an ACE with a length byte value of 0 or until 

it reaches the end of the buffer as indicated by XABSW_ACLSIZ. The ACL 
buffer is used as input to a Create service and as output from an Open or 
Display service. The address in XAB$L_ACLBUF is used only as input to 
these services. 


During a Create operation, if the XAB$L_ACLBUF field has a value other 
than 0, VAX RMS attempts to create the file using the value in the ACL 
buffer. When the XAB$L_ACLBUF field has a value of 0 during a Create 
operation, the file has an ACL only if an ACL is specified by the systemwide 
defaults. Once a file has been created, the ACL cannot be changed using 
VMS RMS. 


During an Open or a Display operation, if the XAB$L_ACLBUF field has a 
value other than 0, VMS RMS passes this address to the file system. The file 
system then fills the user’s buffer with the file’s ACL (in binary format). If 
the entire ACL does not fit into the user’s buffer the file system puts only as 
many ACEs into the buffer as possible. (See the XAB$L_ACLCTX field for 
more information.) 


You can convert an ASCII ACL to binary format by using the $PARSE_ACL 
system service, and you can convert an ACL from binary format to ASCII 
using the $FORMAT_ACL system service. For information about using the 
$PARSE_ACL and $FORMAT_ACL services, see the VMS System Services 
Reference Manual. 


The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.3. XABSL_ACLCTX Field 
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The XAB$L_ACLCTX field is used as a place holder by VMS RMS, and it 
is used as an input and output field by VMS RMS during Open and Display 
operations when the XAB$L_ACLBUF field has a value other than 0. In 
order to read an ACL beginning with the first ACE, the XAB$L_ACLCTX 
field must have a value of 0. When the initial Open or Display operation is 
complete, VMS RMS fills the XAB$L_ACLCTX field with a value that serves 
as a context field, allowing subsequent Open or Display operations that read 
the remainder of the ACL (if the entire list of ACEs did not fit into the user’s 
buffer). 
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For example, suppose you perform an Open operation, find that the value of 
XAB$W_ACLLEN is greater than the ACL buffer, and then perform Display 
operations until all of the ACEs in the ACL have been returned. You can then 
reread the entire ACL on subsequent Opens or Displays only if you set the 
value of the XAB$L_ACLCTX field to 0. 


The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.4 XABSW-_ACLLEN Field 


The ACL length (ACLLEN) field receives the length (in bytes) of the access 
control list for the file during an Open or a Display operation. If the file has 
no ACL, the XABSW_ACLLEN field has a value of 0. 


If the file has an ACL that fits in the user’s buffer, the value of the XABSW_ 
ACLLEN field is equal to the number of bytes in the ACL. Even if the file’s 
ACL does not fit into the user’s buffer, the value of the XAB$W_ACLLEN 
field is still equal to the number of bytes in the ACL (not just the length of 
that portion that fits into the buffer). 


To determine the number of ACL entries that are in the user’s buffer, you 
must process binary ACEs until you find an ACE with a value of 0 or until 
you come to the end of the buffer. 


The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.5 XAB$W_ACLSIZ Field 


The ACL buffer size (ACLSIZ) field specifies the length of the user buffer that 
contains (or will contain) binary ACEs used as input to a Create service and 
as Output to an Open or Display service. 


VMS RMS passes all information, including the ACL buffer, to and from the 
file system using buffered I/O operations. VMS RMS limits buffered I/O 
transfers to 512 bytes, excluding the ACL buffer. Therefore, the size of the 
ACL buffer plus 512 bytes cannot exceed either the BYTLM quota for the 
process or the MAXBUF value for the system. 


The use of this field for DECnet remote file access is not supported. This field 
is ignored during DECnet operations. 


14.6 XABS$L_ACLSTS Field 


The ACL error status (ACLSTS) field contains a system error status relating 
to the processing of ACLs. A value is returned to this field upon a successful 
return from a Create, Open, or Display service. 


Whenever you use the XAB$L_ACLBUF, XAB$L_ACLCTX, XAB$W_ 
ACLLEN, or XAB$W_ACLSIZ fields, be sure to use the following error- 
handling guidelines: 


e If the FAB$L_STS field (RO) contains an error status, handle the error in 
the usual manner. 
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e If the FAB$L_STS field (RO) contains a success status, then you must 
check the value in XAB$L_ACLSTS. If XAB$L_ACLSTS contains a 
success status, then the entire operation completed successfully and 
no further action is required; if XAB$L_ACLSTS contains an error 
status, handle the error appropriately. Note that a value is placed in the 
XAB$L_ACLSTS field only when a success status is returned in FAB$L_ 
STS (RO). 


This extra level of error checking is necessary because the success or failure 
of reading and writing ACLs is independent of the success or failure of the 

whole operation. Thus, in the absence of this additional error checking, it is 
possible to create a file successfully even though an ACL error occurred. 


This field is relevant only when an ACL is used with a Create service or when 
an ACL is returned from an Open or Display service. The use of this field for 
DECnet remote file access is not supported, and it is ignored during DECnet 
operations. 


XAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABPRO, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_PROLEN (this is done by the $XABPRO macro). 


XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block 

as an XABPRO. Once set, this field must not be altered unless the control 
block is no longer needed. This field must be initialized to the symbolic value 
XAB$C_PRO (this is done by the $XABPRO macro). 


XABSW_GRP Field 
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The file owner group number (GRP) field contains the half of the XAB$L_— 
UIC field that defines the group number. Refer to the XAB$L_UIC field 
description for additional information. The contents of the XAB$L_UIC field, 
rather than the $XABPRO macro, establish the initial value of the XAB$W_ 
GRP field. 


This field corresponds to the FDL attribute FILE OWNER. 
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14.10 XABSW_MBM Field 


The file owner member number (MBM) field contains the half of the XAB$L_— 
UIC field that defines the member number. Refer to the XAB$L_UIC field 
description for additional information. The contents of the XAB$L_UIC field, 
rather than the $XABPRO macro, establish the initial value of the XAB$W_ 
MBM field. 


This field corresponds to the FDL attribute FILE OWNER. 








14.11 XABSB_MTACC Field 


The magnetic tape accessibility (MTACC) field enables you to access HDR1 
labels for ANSI-labeled magnetic tapes, in compliance with ANSI standards. 
The value specified in the XAB$B_MTACC field is input to the Create service 
and output from the Open and Display services for magnetic tape only. 


The character to be inserted in the accessibility field of the HDR1 label must 
be one of the following: 


e An uppercase letter from A through Z 

e A digit from 0 through 9 
(SPACE) 
{ 


+ ~ereon ~ & xO 


e One of the following special characters: 


aif ] Heo 


Note that if this field is not specified or if the specification is invalid, a space 
character is inserted into the HDR1 accessibility field. 


This field corresponds to the FDL attribute FILE MT_PROTECTION. and it is 
not supported for DECnet operations. 





14.12 XAB$L_NXT Field 


The next XAB address (NXT) field specifies the symbolic address of the next 
XAB in the XAB chain. A value of 0 (the default) indicates that the current 
XAB is the last (or only) XAB in the chain. 
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14.13 XABSW_PRO Field 
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The file protection (PRO) field specifies the access privileges granted to the 
four classes of users: system, owner, group, and world. 


This field consists of four 4-bit subfields; each subfield is a binary options 
field where each possible access privilege has a corresponding bit assignment. 
The file access privileges must be specified in the following order: 


<SYSTEM,OWNER,GROUP,WORLD> 


To deny access, set the appropriate bits in the protection word to 1. If you 
want to grant access to a specific user class, clear the appropriate bit. 


The following list associates each subfield with its symbolic offset: 
e System—XAB$V_SYS 

* Owner—XAB$V_OWN 

¢ Group—XAB$V_GRP 

¢ World—XAB$V_WLD 


Additionally, each access specification has the following mask values: 
¢ No read access—XAB$M_NOREAD 

e No write access—XAB$M_NOWRITE 

e No execute access—XAB$M_—NOEXE 

¢ No delete access—XAB$M—NODEL 


A user is granted the maximum number of types of access rights for each of 
the classes to which he belongs. 


Each access code consists of four bits for each user class, or four subfields 
in the word identified by XAB$W_PRO. This field is organized as shown in 
Figure 14-1. 


Figure 14-1 File Protection Field 
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If you do not explicitly specify file protection when you invoke the Create 
service, VMS RMS attempts to determine file protection in the following 
order: 


1 Using the protection assigned to an existing file of the same name 
2 Using the default file protection of the directory 


3 Using the process-default protection 


The following chart provides detailed descriptions of the four user classes: 


User Class Description 


System Specifies access rights for users executing under a system 
UIC, that is, users whose group number is less than the value 
for a system UIC, which is defined by the system manager 
(usually 10 or less). 


Owner Specifies access rights for the owner of the file. A user is 
considered the owner of the file only if both the group and 
member number fields of the accessing process match the 
group and member number fields of the file owner's UIC 
stored with the file. 


Group Specifies the access rights for users whose group number 
matches the group number field of the file owner. 


World Specifies access rights for all users. World access is used for 
granting access to users who are not in the system, owner, 
or group classifications. 


This field corresponds to the FDL attribute FILE PROTECTION. 


14.14 XAB$B_PROT_OPT Field 


The ACL file protection (PROT_OPT) field provides a single option, the 
XAB$V_PROPAGATE option, which is used as input during an Enter or 
a Rename operation. (During a Rename operation, the protection XAB is 
assumed to be attached to FAB2.) 


The XAB$B_PROT_OPT field is a binary options field where each file 
protection option has a corresponding bit assignment. Options are identified 
using mnemonics, and each option has its own symbolic offset and mask 
value. For example, the PROPAGATE option has a symbolic offset of 
XAB$V_PROPAGATE and a mask value of XABS{M_PROPAGATE. 


If the XAB$V_PROPAGATE bit is set in this field during either an Enter or 
Rename operation, the file receives new security attributes when the new 
directory entry is made. These security attributes follow the same rules as 
apply during a Create operation. For example, if a lower version of a new file 
exists, the new file inherits the security attributes of the next lower version of 
the file. If the XAB$V_PROPAGATE bit is not set, the security attributes of 
the new file do not change. 


This field is not supported for DECnet operations; it is ignored. 
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14.15 XAB$L_UIC Field 
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The user identification code (UIC) field combines the two XABPRO fields that 
define the UIC of the owner of a file: the XABSW_GRP (group number) and 
XAB$W_MBM (member number) fields. Both numbers are octal numbers. 
The valid range for a group number is 0 to 37777; the valid range for a 
member number is 0 to 177777. Note that the maximum value in each case 
(37777 and 177777) is reserved for DIGITAL use only. This field corresponds 
to the FDL attribute FILE OWNER. 


The symbolic offsets for the group number field and the member number 
field respectively are XABSW_GRP and XABSW_MBM. 


The total user identification field, including both the group and member 
number fields, has a symbolic offset of XAB$L_UIC. 


Note that if no file protection XAB is provided or if the user identification 
field is null for a Create service, VMS RMS determines the owner’s UIC using 
the following logical order: 


1 The owner UIC of an existing version of the file if the creating process 
has ownership rights to the previous version. 


2 The owner UIC of the parent directory, if the creating process has 
ownership privileges to the parent directory. 


3 The UIC of the creating process. 


If you wish to create an output file with a UIC different from your own, you 
must have system privilege (SYSPRV). 


1 5 Revision Date and Time XAB (XABRDT) 


The revision date and time XAB (XABRDT) specifies the revision date and 
time and the revision number when a Close service is invoked for a file. The 
XABRDT operates much like the Date and Time XAB (XABDAT) when input 
to the Create, Open, or Display services. However, when you gain access to 
a file for writing, issuing a Close service for that file causes the revision date 
and time to be set from the current date and time and the revision number to 
be incremented. Thus, any revision date and time value you specify through 
the XAB on a Create service is lost. 


You can input the XABRDT to a Close service and cause the file’s revision 
date and time and revision number to take on the specified values. If you 
want to change the revision date and time when you close the file, you must 
have write access to the file and have accessed the file for some type of 
modification (Put, Update, Delete, or Truncate). 





15.1 Summary of Fields 
The two XABRDT fields that specify revision information are described below. 


¢ Revision date and time (XAB$Q_RDT) is a 64-bit binary field that 
indicates the date and time at which the file was last updated. 


¢ Revision number (XAB$W_RVN) indicates how many times this file has 
been opened for write operations. 


The following list describes how these two XABRDT fields are used by the 
VMS RMS file-processing services. 


Service XAB$Q_RDT XAB$SW_RVN 
Close Input Input 

Create Input Input 

Display Output Output 

Erase Not used Not used 
Extend Not used Not used 
Open Output Output 


If you specify a revision date and time of 0, VMS RMS substitutes the current 
date and time when you close the file. If the XABRDT is present when you 
invoke an Open (or a Display) service, the XAB$Q_RDT field contains the 
file’s revision date and time value. Because the XAB$Q_RDT field is filled 
(not 0), VMS RMS does not substitute the current date and time. 


Use the XABRDT block only to specify a new (nondefault) value for the 
XAB$Q_RDT and XAB$W_RVN fields. You must set these fields between 
the time you invoke the Open service and the time you invoke the Close 
service. If you set the XAB$Q_RDT and XAB$W_RVN fields before you 
invoke the Open service, the file’s revision date, time and number override 
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the specified values. To determine the contents of the XABSQ_RDT and 
XAB$W_RVN fields, examine the appropriate fields of the XABDAT block. 


The symbolic offset, size, FDL equivalent, and a brief description of each 
XABRDT field are presented in Table 15-1. 


Table 15-1 XABRDT Fields 


Field Offset oe FDL Equivalent Description 
XAB$B_BLN' 1 None Block length 
XAB$B_COD' 1 None Type code 
XAB$L_NXT 4 None Next XAB address 
XAB$O_RDT? 8 DATE REVISION Revision date and time 
XABSW_RVN? 2 FILE REVISION Revision number 


'This field is statically initialized by the $XABRDT macro to identify this control block as a 
XABRDT. 

2This field cannot be initialized by the $XABRDT macro; it must be specified before you 
invoke the Close service to be used as input to the Close service. 


Each XABRDT field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS systems. For 
information about the support of VMS RMS options for remote file access to 
other systems, see the VMS Networking Manual. 


The format and arguments of the $XABRDT and $XABRDT_STORE services 
are defined in Appendix B. 


XAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABRDT, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_RDTLEN by the $XABRDT macro. 


XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block as 
an XABRDT. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
RDT by the $XABRDT macro. 


XABS$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 
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15.5 XAB$Q_RDT Field 


The revision date and time (RDT) field contains a 64-bit binary value 
expressing the date and time at which the file was last updated. Note that 
this field is limited to a granularity of 1 second for remote files. 


This field corresponds to the FDL attribute DATE REVISION. 





15.6 XABSW_RVN Field 


The revision number (RVN) field contains a numeric value that indicates the 
number of times this file was opened for write operations. 


This field corresponds to the FDL attribute FILE REVISION. 
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16 Recovery Unit XAB (XKABRU) 


The recovery unit XAB ($XABRU) control block supports the use of recovery 
units to assure data file integrity. See the VAX RMS Journaling Manual for 
details. 
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1 7 Summary XAB (XABSUM) 


The summary XAB (XABSUM) can be associated with a FAB at the time a 
Create, Open, or Display service is invoked. The presence of this XAB during 
these calls allows VMS RMS to return to your program the total number of 
keys and allocation areas defined and the version number when the file was 
created. Note that an XABSUM is used only with indexed files. 





17.1 Summary of Fields 


The symbolic offset, size, and a brief description of each XABSUM field are 
presented in Table 17-1. 


Table 17—1 XABSUM Fields 


Field Offset Size Description 

~ XAB$B_BLN' Byte Block length 
XAB$B_COD' Byte Type code 
XAB$B_NOA? Byte Number of allocation areas defined for the file 
XAB$B_NOK? Byte Numbers of keys defined for the file 
XAB$L_NXT Longword Next XAB address 
XABSW_PVN? Word Prolog version number 


'This field is statically initialized by the $XABSUM macro to identify this control block as 
an XABSUM. 


2This field cannot be initialized by the $XABSUM macro. 


Each XABSUM field is described below. Unless indicated otherwise, each field 
is supported for DECnet operations using remote files with a VMS system as 
the remote node. Note that the words “DECnet operations” in the following 
descriptions refer to remote file operations between two VMS Version 5.0 
systems. See the VMS Networking Manual for information about the support 
of VMS RMS options for remote file access to other systems. 


The format and arguments of the $XABSUM and $XABSUM_STORE macros 
are defined in Appendix B. 





17.2. XABS$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABSUM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_SUMLEN by the $XABSUM macro. 
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XAB$B_COD Field 


The type code (COD) field is a static field that identifies this control block as 
an XABSUM. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
SUM by the $XABSUM macro. 





XAB$B_NOA Field 


The number of allocation areas (NOA) field indicates the number of allocation 
areas defined when the file was created. Refer to Chapter 8 for information 
about multiple allocation areas. 





XAB$B_NOK Field 


The number of keys (NOK) field indicates the number of keys defined when 
the file was created. Refer to Chapter 13 for more information. 





XAB$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB. A value of 0 (the default) indicates that the current XAB is the last (or 
only) XAB in the chain. 





XABS$W_PVN Field 


The prolog version number (PVN) contains a numeric value that indicates 
the prolog number defined when the file was created. For more information 
about prolog numbers, refer to Chapter 13. 
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18 Terminal XAB (XABTRM) 


The terminal XAB (XABTRM) allows extended terminal read operations to 
occur when a VMS RMS Get service is used for a terminal device. Unlike 
most other XABs, the XABTRM is associated with a RAB (record stream). The 
XABTRM provides information that VMS RMS passes to the terminal driver 
to process a user-defined item list that defines the terminal read operation. 


18.1 Summary of Fields 


The symbolic offset, size, and a brief description of each XABTRM field are 
presented in Table 18-1. 


Table 18-1 XABTRM Fields 





Size 
Field Offset (Bytes) Description 
XAB$B_BLN' 1 Block length 
XAB$B_COD' 1 Type code 
XAB$L_ITMLST 4 Item list address 
XAB$W_ITMLST_LEN 2 Item list length 
XAB$L_NXT 4 


Next XAB address 





This field is statically initialized by the $XABTRM macro to identify this control block as 
an XABTRM. 





To perform the extended terminal réad operation, the following information 

is required: 

e In the RAB, the RAB$L_ROP field RAB$V_ETO option must be specified 
(set). 


In the RAB, the RAB$L_XAB field must contain the address of the 
XABTRM. 


In the XABTRM, the XAB$L_ITMLST and XAB$W_ITMLST_LEN fields 
must contain the starting address and length of a valid terminal driver 
read function item list. 


The item list must be supplied according to the conventions described 
for creating an item list for the terminal driver in the VMS I/O User's 
Reference Manual: Part I in the VMS 1/O User’s Reference Volume. 


An item list consists of one or more item list entries, where each itern 
defines an attribute of the terminal read operation. Instead of defining 
terminal read arguments in the RAB, all such arguments (including certain 
arguments only available with the item list method) are defined in the 
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item list. The following list shows the RAB$L_ROP options related to a 
terminal read operation and the equivalent item codes: 


RAB$L_ROP 

Bit Offset Item Code 

RAB$V_CVT TRM$_.MODIFIERS, bit TRM$M_TM_CVTLOW 
RAB$V_PMT TRM$_PROMPT 

RAB$V_PTA TRM$_MODIFIERS, bit TRM$M_—TM_PURGE 
RAB$V_RNE TRM$_MODIFIERS, bit TRM$M_—TM_—NOECHO 
RAB$V_RNF TRM$_MODIFIERS, bit TRM$M_—TM_NOFILTR 
RAB$V_TMO TRM$_TIMEOUT 


Each item code required for the terminal read operation is placed in an 
item list along with other required information. Each item code is made 
up of three longwords. Note that VMS RMS does not validate the item 
list. If the item list is invalid, VMS RMS returns RMS$_QIO status in 
the RAB$L_STS field and the specific terminal driver QIO status in the 
RAB$L_STV field (see the VMS I/O User's Reference Manual: Part I in 
the VMS I/O User’s Reference Volume). 


Each XABTRM field is described below. The XABTRM is not supported for 
DECnet operations between two VMS systems. Thus, access to XABTRM 
fields for DECnet operations is not supported. There are no equivalent FDL 
attributes for the XABTRM fields. 


The format and arguments of the $XABTRM macro and the $XABTRM— 
STORE macro are defined in Appendix B. 


18.2  XAB$B_BLN Field 


The block length (BLN) field is a static field that defines the length of the 
XABTRM, in bytes. Once set, this field must not be altered unless the control 
block is no longer needed. This field is initialized to the symbolic value 
XAB$C_TRMLEN by the $XABTRM macro. 


18.3. XABS$B_COD Field 


The type code (COD) field is a static field that identifies this control block as 
an XABTRM. Once set, this field must not be altered unless the control block 
is no longer needed. This field is initialized to the symbolic value XAB$C_ 
TRM by the $XABTRM macro. 


18.4 XABS$L_ITMLST Field 


The item list address (ITMLST) field contains the symbolic address of the item 
list that defines the extended terminal read operation. 
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18.5 XABS$W_ITMLST_LEN Field 


The item list length (ITMLST_LEN) field contains a numeric value that 
indicates the length of the item list, in bytes. 





18.6 XAB$L_NXT Field 


The next XAB address (NXT) field contains the symbolic address of the next 
XAB to be used. A value of 0 (the default) indicates that the current XAB is 
the last (or only) XAB in the chain. 





VMS RMS Services 


Part Ill, VMS RMS Services, lists the format of each VMS RMS service and 
describes each service in detail. Each VMS RMS service is documented in 
a structured format. See the Introduction to VMS System Routines for a 
discussion of the format and how it is used. 


Note that the calling format for each service requires a place holder (a 
comma) if you omit the first optional argument (err) but include the second 
optional argument (suc). 


VMS RMS Services 
$CLOSE 


$CLOSE 


The Close service terminates file processing and closes the file. This 
service performs an implicit Disconnect service for all record streams 
associated with the file. 








FORMAT SYS$CLOSE §fab/,/err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 





ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Close service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


Suc 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


RMS—4 


You can invoke the Close service only when no operation is currently under 
way (by your process) for the file being processed; that is, when no VMS 
RMS requests for the file are outstanding. When this condition is satisfied, 
the file can be closed to set the internal file identifier field to 0. 


When the Close service is invoked properly, VMS RMS disconnects all RABs 
for you, performs the various cleanup procedures (including file option 
processing and XAB processing), and closes the file. The only types of XABs 
that the Close service processes are the file protection XAB (XABPRO) and 
revision date and time XAB (XABRDT). It processes these XABs only if the file 
was opened or created for write access. 


If a process tries to implement the truncate service when closing a sequential 
file, it must have sole write access to the file. If other processes have write 
access to the file, it remains accessible until all processes have completed. 

If other processes have the file open for read access, VMS RMS defers the 
truncation until the final process having read access closes the file. 


Table RMS-1 lists the control block fields read as input by the Close service. 
Note that if the FAB$V_DLT, FAB$V_SCF, or the FAB$V_SPL bits are set 
by the associated Open or Create service, VMS RMS does not act on them 
for the Close service. For example, if you open the file and specify that it be 
deleted on close by setting the FAB$V_DLT bit, the file is deleted by VMS 
RMS when it is closed regardless of the bit’s state when the Close service is 
invoked. 


For additional information on the fields accessed by this service, see Part II. 


Table RMS-1 Close Service FAB and XAB Input Fields 


Option or 
Field Name XAB Type Description 
FABSW_IFI' Internal file identifier. 
FAB$L_FOP File-processing options. 


FAB$V_DLT Deletes file on close. 
FAB$V_RWC Rewinds a magnetic tape volume. 


FAB$V_SCF? Submits a file as a batch job (sequential files 
only). 

FAB$V_SPL? Submits a file to the print queue (sequential 
files only). 


FAB$V_TEF Truncates data at the end of the file 
(sequential files only). 


FAB$L_XAB Next XAB address. 
XABPRO Modifies file protection and ownership. 
XABRDT Modifies revision date and number. 


1This field is required input to the FAB. 


2This field is not supported for DECnet operations. 


Table RMS-2 lists the control block fields written as output by the Close 
service. 
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$CLOSE 
Table RMS—2 Close Service FAB and XAB Output Fields 
Option or 
Field Name XAB Type Description 
FAB$SW_IFI Internal file identifier (cleared). 
FAB$L_STS Completion status (also returned in register OQ). 
FAB$L_STV Status value. 
FAB$SL_XAB Next XAB address. 
XABRDT New revision date and number returned. 
RETURN The following condition values are described in Appendix A: 
VALUES RMS$_ACT RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BUG_DAP RMS$_BUSY RMS$_CCF RMS$_CDA 
RMS$_COD RMS$_CRC RMS$_DAC RMS$_DME 
RMS$_DNR RMS$._EXENOLM RMS$_FAB RMS$_IF| 
RMS$_IMX RMS$_MKD RMS$_NET RMS$_NETFAIL 
RMS$_NORMAL RMS$_PRV RMS$_SPL RMS$_STR 
RMS$_SUC RMS$_SUP RMS$_SUPPORT RMS$_SYS 
RMS$_WBE RMS$_WER RMS$_WLK RMS$_WPL 
RMS$_XAB 


Note that even though a failure is indicated by the completion status code 
value, the file is closed if VMS RMS clears the internal file identifier value 
(FAB$W_IFI). 
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$CONNECT 


The Connect service establishes a record stream by associating and 
connecting a RAB with a FAB. You can invoke the Connect service only 
for files that are already open. 











FORMAT SYS$CONNECT rab [,[err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Connect service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the Connect service invokes if the 
operation is unsuccessful. The err argument is the address of the entry mask 
of this user-written completion routine. 


SUC 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the Connect service invokes if the 
operation is successful. The suc argument is the address of the entry mask of 
this user-written completion routine. 
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DESCRIPTION 


Any number of RABs can be connected to a FAB if the multistream (FAB$V_ 
MSE) option is selected when the file is opened or created. Each RAB 
represents an independent record stream. 


When you issue a Connect service, VMS RMS allocates an internal 
counterpart for the RAB. This counterpart consists of the internal controls 
needed to support the stream, such as record pointers and request status 
information. All required I/O buffers are also allocated at this time. 


The Connect service also initializes the next record pointer to the first record. 
In indexed files, the key of reference establishes the index of the next record 
pointer. 


If you set the end-of-file (RAB$V_EOF) option in the RAB$L_ROP field 
when issuing a Connect service, VMS RMS examines the organization of the 
file being processed to determine the end-of-file positioning strategy. 


For sequential or relative files, VMS RMS goes to the next record beyond the 
last currently existing record in the file. (The next record is inserted at the 
logical end of the file, and the service returns RMS$_EOF status in response 
to a request for sequential access.) 


For indexed files, VMS RMS verifies that the first record inserted is inserted in 
the proper sort order. If the record cannot be inserted in the proper sort order 
because of user action, VMS RMS returns a sequence error (RMS$_SEQ). 


Get services that specify the sequential record access mode (RAB$B_RAC 

is RAB$6C_SEQ) return an RMS$_EOF status. Get services that specify the 
random access mode (RAB$B_RAC is RAB$C_KEY), ignore (turn off) the 
end-of-file positioning. Positioning to end-of-file is supported for all indexed 
files, regardless of how many indexes the file contains. However, the EOF 
positioning is supported only when you access a file by the primary key. If 
the specified key of reference is a secondary key, an RMS$_ROP message is 
returned. 


In most cases, setting the RAB$V_EOF bit guarantees that the next record is 
inserted at the logical end of the file. However, if a relative file or an indexed 
file is shared by two or more active processes, the following scenario may 


develop. 


Assume that process A has invoked the Connect service after setting the 
RAB$V_EOF bit and is positioned to the end of the file. Before process A can 
do a $PUT, process B inserts a record into the file and changes the current 
record position. When process A attempts to do a $PUT into the position 
that was formerly the end of the file, the record may be inserted improperly. 
It may be inserted either before or after the record inserted by process B, 
depending on the respective key values. Or, the $PUT operation may even 
fail if the keys have the same value and duplicates are not allowed. 


Table RMS-3 lists the control block fields read as input by the Connect 
service. For additional information about the fields accessed by this service, 
see Part II. 
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Table RMS-3 Connect Service RAB Input Fields 





Option or 
Field Name XAB Type Description 
RAB$L_FAB’ File access block address (required to access 
the internal file identifier field, FAB$W_IFI). 
RABSW_ISI' Internal stream identifier (must be 0). 
RAB$B_KRF Key of reference (applies only to indexed 
files). 
RAB$B_MBC? Multiblock count (applies only to sequential 
files residing on disk devices). 
RAB$B_MBF? Multibuffer count. 
RAB$L__ROP Record-processing options: 
RAB$V_ASY Asynchronous: performs Connect service 
asynchronously. 
RAB$V_BIO Block 1/0: specifies that only block I/O 


operations are permitted. The FAB$B_FAC 
field FAB$V_BRO or FAB$V_BIO option must 
be specified to the Open or Create service. 

RAB$V_EOF? End-of-file: positions to the end of the file 
upon execution of the Connect service. 

RAB$V_RAH?2 Read ahead: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 

RAB$V_WBH? Write behind: allocates at least two buffers 
for multibuffering (applies only to sequential 
files on disk devices). 





‘This field is a required input to the Connect service. 
2This field is not supported for DECnet operations. 


3Refer to text for exceptions. 





Table RMS-4 lists the control block fields written as output by the Connect 
service. 


Table RMS—4 Connect Service RAB Output Fields 








Field 

Name Description 

RAB$W_ISI Internal stream identifier. 

RAB$L_STS Completion status code (also returned in Register O). 


AB$L_STV Status value. 
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S$CONNECT 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG_DAP RMS$_CCR 
RMS$_CDA RMS$_CRMP RMS$_DME RMS$_FAB 
RMS$_GBC RMS$_IAL RMS$_IFA RMS$_IFI 
RMS$_KRF RMS$_MBC RMS$_NET RMS$_NETFAIL 
RMS$_NORMAL RMS$_PENDING RMS$_RAB RMS$_RFM 
RMS$_ROP RMS$_RPL RMS$_STR RMS$_SUC 
RMS$_SUP RMS$_SUPPORT 
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$CREATE 


The Create service constructs a new file according to the attributes 

you specify in the FAB. If any XABs are chained to the FAB, then the 
characteristics described in the XABs are applied to the file. This service 
performs implicit Open and Display services. 











FORMAT SYSSCREATE fab [,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB6L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Create service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


Suc 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The Create service first uses the information from the specified FAB. If an 
allocation control XAB is present, however, its allocation quantity (XAB$L_— 
ALQ), allocation options (KAB$B_AOP, only for the XAB$V_CTG and - 
XAB$V_CBT options), bucket size (XAB$B_BKZ), and default extension 
quantity (XABSW_DEQ) fields are used instead of the corresponding fields 

of the FAB. When either key definition or allocation XABs are present, they 
can be grouped in any order. If a name block (NAM) is also connected to the 
FAB, VMS RMS fills in its fields with information about the created file. The 
Create service leaves the file opened. 


When a search list logical name is used, the file is placed in the first resultant 
search list file specification unless the create-if (FAB$V_CIF) option is 
specified. If you select the FAB$V_CIF option, VMS RMS searches all search 
list file specifications to locate the file. If it finds the file, VMS RMS opens it 
rather than create a new file. If VMS RMS does not find the file, it creates a 
new file using the first resultant search list file specification. 


You do not have to explicitly specify the FAB$V_PUT option when invoking 
a Create service because write is the default access mode when you create a 
file. 


Table RMS-5 lists the control block fields read as input by the Create service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—5 Create Service FAB and XAB Input Fields 


Option or 
Field Name XAB Type Description 


FAB$SL_ALO Allocation quantity; ignored if an 
allocation XAB is present. 


FAB$B_BKS Bucket size; ignored if an allocation XAB 
is present. 


FABSW_BLS Block size (applies to magnetic tape 
only). 


FABSW_DEQ Default file extension quantity; ignored if 
an allocation XAB is present. 


FABS$SL_DNA Default file specification string address. 
FAB$B_DNS Default file specification string size. 
FAB$B_FAC File access. , 
FAB$V_BIO Block I/O access to file. 
FAB$V_BRO Biock or record |/O access to file. 
FAB$V_DEL Delete access to file. 
FAB$V_GET' Read access to file. 


FAB$V_PUT' Write access to file and explicit file 
extension. 


FAB$SV_TRN Truncate access to file. 


FAB$V_UPD Update access to file and explicit file 
extension. 


'These are the default values supplied by VMS RMS. 
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Table RMS —5 (Cont.) Create Service FAB and XAB Input Fields 


Field Name 
FAB$L_FNA? 
FAB$B_FNS? 
FAB$L_FOP 


FAB$V_CHAN_ 
MODE? 


FABSV_LNM_ 
MODE? 


Option or 
XAB Type 


FAB$V_CBT 


FABS$V_CIF 


FAB$V_CTG 


FAB$V_DFW? 


FAB$V_DLT 


FABSV_MXV 


FABSV_NAM®? 


FAB$V_NFS? 


FAB$V_OFP 


Description 

File specification string address. 
File specification string size. 
File-processing options. 


Contiguous best try: indicates that the 
file is to be allocated contiguously on 
a “best effort” basis. If VMS RMS is 
unable to allocate the file within three 
extents, this bit is switched off by the 
Create service. To specify a single 
extent, use the FAB$V_CTG option. 


Create-if: opens a file if it already exists 
or creates a file if it does not already 
exist. 


Contiguous: indicates that the space for 
a file is to be allocated contiguously. 


Assigns the channel access mode. 


Deferred write: writing back to the file 
from the modified buffer is deferred. 
Applies to relative and indexed files 
and sequential files opened for shared 
access. 


Delete: indicates that the file is to be 
deleted when closed. 


Specifies the logical name translation 
access mode. 


Maximize version: indicates that the 
created file be given the specific version 
number requested or a version number 
that is one greater than the highest 
version number of an existing file. 


Name block inputs: indicates that the 
NAM$W_DID and NAM$T_DVI fields 
in the specified NAM block are used as 
input. 


Non-file-structured: indicates that the 
accessed volume is to be processed in a 
non-file-structured manner. 


Output file parse: specifies that the 
resultant file specification string of the 
related file, if used, is to provide file 
name and file type defaults only. 


2These fields must be specified unless you select the FAB$V_TMD or the FAB$V_TMP 


option. 


3This field is not supported for DECnet operations. 
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Table RMS—5 (Cont.) Create Service FAB and XAB Input Fields 


Field Name 


FAB$B_FSZ 
FAB$W_GBC? 


Option or 
XAB Type 


FAB$V_POS 


FABS$V_RCK 


FABSV_RWC 
FAB$V_RWO 


FAB$V_SCF 


FABSV_SPL 


FABSV_SQO 


FAB$V_SUP 


FABSV_TEF 


FAB$V_TMD 


FABSV_TMP 


FAB$V_UFO? 


FABSV_WCK 


Description 


Current position (applies to magnetic 
tapes only). 


Read-check: indicates that transfers 
from disk are to be followed by a 
read-compare operation. 


Rewind on close (applies to magnetic 
tape only). 


Rewind on open (applies to magnetic 
tape only). 


Submit command file: indicates that 

the file is to be submitted as a batch- 
command file to the process default 
batch queue (SYS$BATCH) when the file 
is closed (applies to sequential files only). 


Spool: indicates that the file is to be 
spooled to the process default print 
queue (SYS$PRINT) when the file is 
closed (applies to sequential files only). 


Sequential only: indicates that the file 
can be processed in a sequential manner 
only, usually to enable DECnet—VAxX file 
transfer. 


Supersede: allows an existing file to be 
superseded by a new file of the same 
name, type, and version. 


Truncate at end of file: indicates that 
the unused space allocated to a file 
is deallocated when that file is closed 
(applies to sequential files only). 


Temporary marked for delete: indicates 
that a temporary file is to be created, 
and then deleted when the file is closed. 


Temporary: indicates that a temporary 
file is to be created and retained, but no 
directory entry is made for this file. 


User file open: indicates that the file is 
to be created or opened only (no further 
processing of that file by VMS RMS is 
allowed). 


Write-check: indicates that transfers 
to disk are to be followed by a read- 
compare operation. 


Fixed control area size. 


Global buffer count for shared files. 


3This field is not supported for DECnet operations. 
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Table RMS—5 (Cont.) Create Service FAB and XAB Input Fields 


Field Name 


Option or 
XAB Type 


Description 





FABSW_IFI 
FABSL_MRN 


FABSW_MRS 
FABSL_NAM 
FABSB_ORG 


FABSB_RAT 
FAB$B_RFM 


FAB$B_RTV? 
FAB$B_SHR 


FABSL_XAB 


FAB$V_SHRDEL 


FAB$V_SHRGET 


FAB$V_MSE? 
FAB$SV_NIL 


FAB$V_SHRPUT 
FAB$V_SHRUPD 


FAB$V_UPI 


XABALL 
XABDAT 
XABFHC 


Internal file identifier (must be O). 


Maximum record number (applies to 
relative files and sequential files having 
fixed-length 512-byte records). 


Maximum record size. 
Name block address. 
File organization: sequential (FAB$C_ 


SEQ'), relative (FAB$C_REL), or indexed 
(FAB$C_IDX). 


Record attributes. 


Record format: fixed-length (FAB$C_ 
FIX), variable-length (FAB$C_VAR), 
VFC (FAB$C_VFC), stream (FAB$C_ 
STM), stream with line feed terminator 
(FABS$C_STMLF), stream with carriage 
return terminator (FAB$C_STMCR), or 
unidentified format (FAB$C_UDF'). 


Retrieval window size. 
File sharing. 


Allows other users to delete records 
from the file. 


Allows other users to read the file; also 
used with the FAB$V_MSE and FAB$V_ 
GET bits to specify a read-only global 
buffer cache when global buffering is 
enabled. 

Allows multistream access. 

Prohibits any type of file sharing by other 
users. 

Allows other users to write records to 
the file and extend it. 

Allows other users to update records in 
the file and extend it. 


Allows one or more users write access 
to a shared file open for block |/O 
(applies to sequential files only). 


Extended attribute block address. 
Allocation XAB; see Chapter 8. 
Date and time XAB; see Chapter 9. 


File header characteristics XAB; see 
Chapter 10. 


1These are the default values supplied by VMS RMS. 


3This field is not supported for DECnet operations. 
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Table RMS—5 (Cont.) Create Service FAB and XAB Input Fields 


Option or 
XAB Type 


XABITM 
XABKEY 
XABPRO 
XABRDT 


Field Name 


XABSUM 


Description 

Item list XAB; see Chapter 11. 

Key definition XAB; see Chapter 13. 
Protection XAB; see Chapter 14. 


Revision date and time XAB; see 
Chapter 15. 


Summary XAB; see Chapter 17. 


Table RMS-6 lists the control block fields written as output by the Create 


service. 


Table RMS-6 Create Service FAB and XAB Output Fields 


Option or 


Field Name XAB Type 


FAB$L_ALO 


FAB$B_BKS 


FABSW_BLS 


FABSW_DEQ 
FABSL_DEV 
FABSB_FAC 
FABSL_FOP 
FAB$V_CBT 


FABS$B_FSZ 


FAB$W_GBC 
FABSW_IFI 
FABSL_MRN 
FAB$W_MRS 
FAB$B_ORG 
FABSB_RAT 
FAB$B_RFM 
FAB$L__SDC 
FABS$B_SHR 


Description 
Allocation quantity: contains actual number 
of blocks allocated. 


Bucket size: applies only to relative and 
indexed files. When multiple areas are 
defined for an indexed file, the largest 
bucket size is returned. 


Device block size (applies to files of 
sequential organization only). 


Default file extension quantity. 
Device characteristics. 

File access. 

File-processing option. 


If this bit is set on input and remains on 
as Output, it indicates that the file was 
allocated within three extents. 


Fixed-length control area size for VFC 
format. 


Global buffer count. 

Internal file identifier. 

Maximum record number. 
Maximum record size. 

File organization. 

Record attributes. 

Record format. 

Secondary device characteristics. 


File sharing. 
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Table RMS—6 (Cont.) Create Service FAB and XAB Output Fields 


Field Name 


FAB$L_STS 


FAB$L_STV 


FABSL_XAB 


Option or 
XAB Type 


XABALL 
XABDAT 
XABFHC 


XABITM 
XABKEY 
XABPRO 
XABRDT 


XABSUM 


Description 


Completion status code (also returned in 
register 0). 


Status value: contains the I/O channel 
number if the operation is successful. 


Next XAB field. 
Allocation XAB; see Chapter 8. 
Date and time XAB; see Chapter 9. 


File header characteristics XAB; see 
Chapter 10. 


Item list XAB; see Chapter 11. 
Key definition XAB; see Chapter 13. 
Protection XAB; see Chapter 14. 


Revision date and time XAB; see 
Chapter 15. 


Summary XAB; see Chapter 17. 


Use of the NAM Block for Creating Files 


Table RMS-7 and Table RMS-§8 list the NAM block fields that VMS RMS 
uses as input and output for the Create service (provided that the name block 
address field (FAB$L_NAM) is specified). 


Table RMS—7 Create Service NAM Block Input Fields 


Field Name 


NAM$W_DID' 


NAM$T_DVI' 


NAMS$L_ESA 
NAM$B_ESS 
NAM$B_NOP 


Option 


NAM$V_PWD 


Description. 


Directory identification (input only if 
the FAB$L_FOP FAB$V_NAM option 
is set). 

Device identification (input only if the 


FAB$L_FOP FAB$V_NAM option is 
set). 


Expanded string area address. 
Expanded string area size. 

NAM block options. 

Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 


and resultant strings (instead of being 
replaced by the word “password"). 


'This field is not supported for DECnet operations. 
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Table RMS—7 (Cont.) Create Service NAM Block Input Fields 
Field Name Option Description. 


NAM$V_NOCONCEAL Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by the 
actual physical device name in the 
resultant string. 


NAMS$L __RLF Related file NAM block address. 


NAM$L_RSA Related file NAM block resultant string 
address. 


NAM$B_RSL Related file NAM block resultant string 
length. 


NAMS$L_FNB Related file NAM block file name 
status bits. 


NAMS$L_RSA Resultant string area address. 
NAM$B_RSS Resultant string area size. 


Table RMS-8 Create Service NAM Block Output Fields 
Field Name Description 


NAM$W_DID' Directory identification. 
NAM$T_DVI' Device identification. 


NAM$B_ESL Expanded string length. If the NAM$L_ESA field and the 
NAM$B_ESS field are nonzero, and you do not select the 
FAB$V_NAM option, or if the NAM$W_DID field is clear when 
you invoke the Create service, VMS RMS copies the expanded 
file specification string to the buffer specified by the NAM$L_ 
ESA field. 

NAM$W_FID' _ File identification. 

NAMSL_FNB File name status bits. This is an output field from the Create 
service only if the NAM bit in FAB$SL_FOP field is clear, or if 
the NAM$W_DID field is clear when you invoke the Create 
service. 

NAM$B_RSL Resultant string length. If the NAM$L_RSA field and the 
NAM$B_RSS field are both nonzero on input, the resultant file 
specification is copied to the buffer specified by NAM$L_RSA. 


This field is not supported for DECnet operations. 


Creating Files with the Create-If Option 


Note that setting the create-if (FAB$V_CIF) option in the FAB$L_FOP field 
specifies that if a new file has the same file specification as an existing file, 
VMS RMS opens the existing file and no new file is created. Some fields 

in the FAB, such as the file organization (FAB$B_ORG) and record format 
(FAB$B_RFM) fields, are input to a Create service, but are output from an 
Open service. For example, the indexed file organization could be specified 
in the FAB$B_ORG field on a create-if operation. However, if an existing 
sequential file has the same file specification as the indexed file that the user 
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is attempting to create, then the existing file is opened and the FAB$B_ORG 
field is set to sequential. 


Creating Indexed Files 


An indexed file consists of a prolog, with which it begins, and one or more 
index structures. VMS RMS supplies the prolog with certain information 
about the file, including file attributes. 


VMS RMS supports two prolog levels, called Prolog 2 and Prolog 3. Unlike 
Prolog 2 files, Prolog 3 files allow for file compression and additional key 
types. For compatibility with RMS-11 data files that are transported or copied 
(without conversion) between systems, you may want to choose Prolog 2. 


If you want to create a Prolog 3 file, you must be sure that records in the 
file are not larger than 32,224 bytes and, if the primary key is segmented, 
that the segments of the primary key do not overlap (one or more bytes of 
the record are used in more than one segment). If the primary key contains 
overlapping segments, you can consider using that key as an alternate key 
instead of a primary key or you can request (or let VMS RMS assign you) a 
Prolog 2 indexed file. 


Prolog 3 is the default prolog for VMS RMS, although VMS RMS creates a 
Prolog 2 file only if the key characteristics are not compatible with Prolog 3 
files. You can, however, override this default by requesting a specific prolog 
version. The option you choose in requesting a specific prolog level affects 
the behavior of VMS RMS with regard to creating the file and returning error 
messages. 


If you explicitly request a prolog version using the XABKEY XAB$B_. 
PROLOG field in an application program, and if other file characteristics 

are incompatible with that prolog, then VMS RMS returns an error message 
and does not attempt to create the file. For example, if you explicitly specify 
Prolog 2 in the XAB$B_PROLOG field and have requested a key type that is 
available only with Prolog 3 (such as an 8-byte integer key type), an error is 
returned and the file is not created. 


However, if a specific prolog version is not explicitly requested in the XAB$B_ 
PROLOG field, VMS RMS selects the greatest prolog level that can support 
the specified key characteristics and does not return an error completion code. 


In summary, there are two ways in which you can specify a particular prolog 
version: 


¢ Specify the XAB$B_PROLOG field in an XABKEY block in an application 
program, affecting only the file being created. 


e Use the DCL command SET RMS_DEFAULT/PROLOG to change the 
process default. 


If you do not specify the XAB$B_PROLOG field in your application program, 
VMS RMS examines your process defaults to check for prolog information. If 
this information is not specified in your process defaults, VMS RMS examines 
the system defaults. If no prolog information is specified at the system level, 
VMS RMS attempts to create a Prolog 3 file. 
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You need not be concerned with the distinctions between Prolog 2 and Prolog 
1 files. To create an indexed file with a prolog version other than Prolog 

3, specify a Prolog 2 file. If all keys in the file are string keys, VMS RMS 
provides a default of Prolog 1; in all other cases, Prolog 2 is the default. If 
the file contains all string keys and Prolog 2 is requested, VMS RMS attempts 
to create a Prolog 1 file only if no binary keys are present. 


Note that RMS-11 and previous versions of VMS RMS return error messages 


if requested to process Prolog 3 files. 


If a failure is indicated, the file may be created, but it may not be opened for 
processing, depending on the nature of the failure. 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACS 
RMS$_ALN 
RMS$_ATR 
RMS$_BKZ 


RMS$_BUG_DAP 


RMS$_CHN 


RMS$_CREATED 


RMS$_DAN 
RMS$_DIR 
RMS$_DNF 
RMS$_DVI 
RMS$_ESA 
RMS$_EXP 
RMS$_FLG 
RMS$_FNF 
RMS$_FSZ 
RMS$_IAL 
RMS$_IFA 
RMS$_IMX 
RMS$_KSI 
RMS$_MRN 
RMS$_NET 


RMS$_NORMAL 


RMS$_POS 
RMS$_RAT 


RMS$_ACT 
RMS$_ALO. 
RMS$_ATW 
RMS$_BLN 


RMS$_BUG_DDI 


RMS$_COD 


RMS$_CRE_STM 


RMS$_DEV 
RMS$_DME 
RMS$_DNR 
RMS$_ENQ 
RMS$_ESS 
RMS$_FAB 
RMS$_FLK 
RMS$_FNM 
RMS$_FUL 
RMS$_IAN 
RMS$_IF1 
RMS$_IOP 
RMS$_LAN 
RMS$_MRS 


RMS$_NETFAIL 


RMS$_NPK 
RMS$_PRV 
RMS$_REF 


RMS$_AID 
RMS$_AOP 
RMS$_BKS 
RMS$_BUG 
RMS$_CDA 
RMS$_.CRE 
RMS$_CRMP 
RMS$_DFL 
RMS$_DNA 
RMS$_DTP 
RMS$_ENV 


RMS$_EXENOLM 


RMS$_FEX 
RMS$_FNA 
RMS$_FOP 
RMS$_GBC 
RMS$_IBK 
RMS$_IFL 
RMS$_KNM 
RMS$_LNE 
RMS$_NAM 
RMS$_NOD 
RMS$_ORG 
RMS$_QUO 
RMS$_REM 
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RMS$_RLF 
RMS$_RST 
RMS$_SHR 
RMS$_SUC 
RMS$_SUPPORT 
RMS$_UPI 
RMS$_WPL 


RMS$_RPL 
RMS$_RUNDOWN 
RMS$_SIZ 
RMS$_SUP 
RMS$_SYN 
RMS$_VER 
RMS$_XAB 


RMS$_RSS 
RMS$_SEG 
RMS$_STR 
RMS$_SUPERSEDE 
RMS$_SYS 
RMS$_WLK 
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The Delete service removes an existing record from a relative or indexed 
file. You cannot use this service when processing sequential files. 











FORMAT SYS$DELETE rab [,/err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RABSL_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Delete service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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$DELETE 

DESCRIPTION A Delete service always applies to the current record. Therefore, immediately 
before invoking the Delete service, you must establish the current record by 
issuing a Find or Get service. 
Table RMS-9 lists the control block fields read as input by the Delete service. 
For additional information on the fields accessed by this service, see Part II. 
Table RMS-—9 _ Delete Service RAB Input Fields 
Field Name Option Description 
RAB$SW_ISI Internal stream identifier (required). 
RAB$L_ROP Record-processing options. 

RAB$V_ASY Asynchronous: performs Delete service 
asynchronously. 
RAB$V_FDL Fast delete (applies to indexed files). 

Table RMS-10 lists the control block fields written as output by the Delete 
service. 
Table RMS—10 Delete Service RAB Output Fields 
Field Name Description 
RAB$L_STS Completion status code (also returned in register QO). 
RAB$L_STV Status value. 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG RMS$_BUG_DAP 
RMS$_CDA RMS$_CHK RMS$_CUR RMS$_DME 
RMS$_DNR RMS$_FAC RMS$_FTM RMS$_IAL 
RMS$_IBF RMS$_IOP RMS$_IRC RMS$_1ISI 
RMS$_NET RMS$_NETFAIL RMS$_NORMAL RMS$_PENDING 
RMS$_RAB RMS$_RNL RMS$_RPL RMS$_RRV 
RMS$_RSA RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_TRE RMS$_WLK 
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$DISCONNECT 


The Disconnect service breaks the connection between a RAB and a FAB, 
thereby terminating a record stream. All system resources, such as |/O 
buffers and data structure space, are deallocated. 











FORMAT SYS$DISCONNECT rab [,[err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS _~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for the 
Disconnect service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Close service (see $CLOSE) performs an implied disconnect for all 
record streams connected to the FAB. Thus, you need not explicitly issue a 
Disconnect service prior to closing the file. However, if more than one RAB 
is connected to a single FAB, then you must explicitly disconnect the desired 
RAB in order to terminate a particular record stream and leave the others 
active. 


Table RMS-11 lists the control block fields read as input by the Disconnect 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-11 Disconnect Service RAB Input Fields 


Field Name Description 


RABSW_ISI Internal stream identifier (required). 


RABS$L__ROP Record-processing option, RAB$V_ASY. Asynchronous: 
performs Disconnect service asynchronously. 


Table RMS-12 lists the control block fields written as output by the 
Disconnect service. 


Table RMS-—12 Disconnect Service RAB Output Fields 


Field Name Description 
RABSW_ISI internal stream identifier (zeroed). 
RAB$L_STS Completion status code (also returned in register 0). 


RAB$L_STV Status value. 





RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BUG_DAP RMS$_CDA RMS$_CRC RMS$_DME 
RMS$_DNR RMS$_1S! RMS$_NET RMS$_NETFAIL 
RMS$_NORMAL RMS$_PENDING RMS$_RAB RMS$_RSA 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_.SUPPORT 
RMS$_SYS RMS$_WBE RMS$_WER RMS$_WLK 
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$DISPLAY 


The Display service retrieves file attribute information about a file and 
places this information in fields in the FAB, in XABs chained to the FAB, 
and in a NAM block (if one is requested). 








FORMAT SYS$DISPLAY fab /[,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 





ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for 
the Display service call. The fab argument is the address of the FAB control 


block. 

err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION A file must be open for access by a Create or Open service before the Display 
service can be invoked. 


VMS RMS places the file attribute information in the corresponding fields of 
the FAB and specified XABs. If the FAB$L_NAM field contains a valid NAM 
block address, certain NAM block fields are filled in, including the resultant 
string, and the NAM$B_NOP options are examined. 


Note that the Open and Create services automatically perform an implicit 
Display service (see $OPEN, $CREATE). 


Table RMS-13 lists the control block fields read as input by the Display 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-—13 Display Service FAB and NAM Input Fields 





Field Name Option Description 
FABSW_IFI Internal file identifier. 
FABSL_NAM' Name block address. 
FAB$L_XAB' Extended attribute block address. 
NAM$B_NOP NAM block options. 
NAM$V_PWD Password: indicates that a password 


contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word “password"). 


NAM$V_NOCONCEAL Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by 
the actual physical device name (and 
directory, if present) in the resultant 
string. 


' if you want information about a particular XAB or NAM block, you must pass it to the 
Display service as input. 


Table RMS-14 lists the control block fields written as output by the Display 
service. 


Table RMS-14 Display Service FAB, NAM, and XAB Output Fields 


Field Name XAB Type Description 

FAB$L_ALO Allocation quantity in blocks. 
FAB$B_BKS Bucket size. 

FABSW_BLS Block size. 

FAB$W_DEO Default file extension quantity. 
FAB$L_DEV Device characteristics. 
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Table RMS—14 (Cont.) Display Service FAB, NAM, and XAB Output 


Field Name 
FAB$B_FAC 
FAB$B_FSZ 
FAB$W_GBC 
FABS$L__MRN 
FABSW_MRS 
FAB$B_ORG 
FAB$B_RAT 
FAB$B_RFM 
FAB$B_RTV 
FAB$B_SHR 
FAB$L_STS 


FABS$L_STV 
FABS$L_XAB 


NAM$W_DID 
NAM$T_DVI 
NAMS$W_FID 
NAMS$L_FNB 
NAM$B_RSL 


Fields 
XAB Type Description 
File access. 


XABALL 
XABDAT 
XABFHC 


XABITM 
XABKEY 
XABPRO 
XABRDT 
XABSUM 


Fixed control area size. 
Global buffer coum. 
Maximum record number. 
Maximum record size. 
File organization. 

Record attributes. 

Record format. 

Retrieval window size. 
File sharing. 


Completion status code (also returned in 
register O). 


Status value. 

Next XAB address. 

Allocation XAB; see Chapter 8. 
Date and time XAB; see Chapter 9. 


File header characteristics XAB; see 
Chapter 10. 


Item list XAB; see Chapter 11. 

Key definition XAB; see Chapter 13. 
Protection XAB; see Chapter 14. 

Revision date and time XAB; see Chapter 15. 
Summary XAB; see Chapter 17. 

Directory identification. 

Device identification. 

File identification. 

File name status bits. 


Resultant string length: indicates the length 
of the resultant string that is written into 
the buffer whose address is contained in the 
NAMS$L _RSA field (if the NAM$L_RSA and 
NAMS$B_RSS fields are nonzero). 
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RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_AID RMS$_ATR RMS$_BLN 
RMS$_BUG_DAP RMS$_CDA RMS$_COD RMS$_DME 
RMS$_DNR RMS$_ESA RMS$_ESL RMS$_ESS 
RMS$_FAB RMS$_IFI RMS$_IMX RMS$_NET 
RMS$_NETFAIL RMS$_NORMAL RMS$_OK_NOP RMS$_PLG 
RMS$_PRV RMS$_REF RMS$_RPL RMS$_STR 
RMS$_SUC RMS$_SUP RMS$_SUPPORT RMS$_XAB 
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The Enter service inserts a file name in a directory. 














FORMAT SYSSENTER  fab/,[err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS _ fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
FAB control block whose contents are to be used as indirect arguments for the 
Enter service call. The fab argument is the address of the FAB control block. 
err | 
VMS usage: ast—_procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 
SUC 
VMS usage: ast—procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
DESCRIPTION The Enter service function is performed automatically by the Create service 


unless you select the FAB$V_TMP option or the FAB$V_TMD option. The 
Enter service, however, allows you to perform this step separately. Note that 
the file must be closed before you invoke the Enter service (FABSW_IFI must 
be 0). 


When you enter a file name in a directory, no file associated with the FAB 
can be open and no wildcard characters can be used. 
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The Enter service requires many NAM block fields as input. You normally 
precede the Enter service with an Open, Create, or Parse service (see $P ARSE) 
and a Search service (see $SEARCH), specifying the same FAB and NAM 
block for each service. 


The optional resultant string is moved to the buffer described by the 
NAM$L_RSA and NAM$B_RSS fields (only if both these fields are nonzero). 
If the file version number of the name string described by the expanded string 
length and address fields of the NAM block is omitted or contains a 0, the 
Enter service scans the entire directory. It assigns a version number that is 
one higher than the highest found (or 1 if none is found). 


The Enter service is not supported for DECnet operations with remote files 
between two VMS systems. 


Table RMS-15 lists the control block fields read as input by the Enter service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—15_ Enter Service FAB and NAM Input Fields 


Field Name Description 





FAB$SW_IFI Internal file identifier (must be 0). 
FABSL_NAM Name block address. 


NAM$W-__DID' Directory identification: identifies the directory in which the 
file name is to be entered. 


NAM$T_DVI' Device identification: identifies the device containing the 
directory in which the file name is to be entered. 


NAMS$L_ESA Expanded string area address: contains file name, type, and 
version to be entered. 

NAM$B_ESL Expanded string length. 

NAM$W_FID' File identification: identifies the file to be entered into the 
directory. 

NAM$L_RSA Resultant string area address. 

NAM$B_RSS Resultant string size. 





'This field is not supported for DECnet operations. 





‘Table RMS-16 lists the control block fields written as output by the Enter 


service. 


Table RMS-—16_ Enter Service FAB and NAM Output Fields 








Field 

Name Description 

FAB$L_STS Completion status code (also returned in register Q). 
FAB$L_STV Status value. 

NAM$B_RSL Resultant string length. 
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RETURN The following condition values are described in Appendix A: 


VALUES RMS$_BLN RMS$_CDA RMS$_CHN RMS$_DEV 
RMS$_DME RMS$_DNF RMS$_DNR  RMS$_DVI 
RMS$_ENT RMS$_ESA RMS$_ESL RMS$_FAB 
RMS$_FNF = RMS$_IFI RMS$_NAM RMS$_NORMAL 
RMS$_PRV RMS$_RSL RMS$_RSS RMS$_RST 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 
RMS$_SYS RMS$_WLD RMS$_WLK 
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SERASE 


The Erase service deletes a VMS RMS disk file and removes the file’s 
directory entry specified in the path to the file. If additional directory 
entries have been created for this file by the Enter service, you must use 
the Remove service to delete them. 











FORMAT SYSSERASE fab [,[err] [, suc] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Erase service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


Using the Erase service to delete a file releases the file’s allocated space for 
use by another file. The Erase service does not physically remove the data (as 
does overwriting or zeroing). 


Note that the file must be closed before you invoke the Erase service 
(FAB$W_IFI must be zero). You can, however, delete a file that is currently 
open, if you issue a Close service and specify the FAB$L_FOP field FAB$V_ 
DLT option. VMS RMS does not allow you to delete files from magnetic tape 
volumes; they must be overwritten. 


If a search list logical name is specified, the file is deleted only if it is found in 
the first resulting search list file specification. 


Table RMS-17 lists the control block fields read as input by the Erase service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—17 Erase Service FAB and NAM Input Fields 


Field Name Option Description 
FABSL_DNA Default file specification string address. 
FAB$B_DNS Default file specification string size. 
FAB$SL_FNA File specification string address. 
FAB$SB_FNS File specification string size. 
FAB$L_FOP File-processing options. 
FABSV_NAM' NAM block inputs: allows use of the 
NAMSW_DID, NAM$T_DVI, and NAM$W_. 
FID fields. 
FAB$SW_IFI Internal file identifier (must be QO). 
FAB$SL_NAM Name biock address. 
NAM$W_DID' Directory identification (input only if the 
FAB$L_FOP field FABS$V_NAM bit is set). 
NAM$T_DVI' Device identification (input only if the 
FAB$L__FOP field FABS$V_NAM bit is set). 
NAM$L_ESA Expanded string area address. 
NAM$B_ESS Expanded string area size. 
NAMSW__FID' File identification (input only if the FAB$SL _ 
FOP field FAB$V_NAM bit is set). 
NAM$L _RLF Related file NAM block address. 
NAM$L_RSA Related file resultant string address. 
NAM$B_RSS Related file resultant string size. 
NAMS$L __FNB Related file filename status bits. 


This field is not supported for DECnet operations. 


Table RMS-18 lists the control block fields written as output by the Erase 


service. Note that the NAM block fields are used for output only if the name 
block address field is specified in the FAB. 
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Table RMS—18 Erase Service FAB and NAM Output Fields 

Field Name Description 

FAB$L__STS Completion status code (also returned in register OQ). 

FAB$L_STV Status value. 

NAM$W_DID' Directory identification. 

NAM$T_DVI' Device identification. 

NAM$B_ESL Expanded string length. If the NAM$L_ESA field and the 
NAM$B_ESS field are nonzero, and if the FAB$V_NAM bit 
is clear or the NAM$W_LDID field contains a zero, VMS RMS 
copies the expanded file specification string to the buffer 
specified by the input NAM$L_ESA field. 

NAMS$L_FNB File name status bits. 

NAM$B_RSL Resultant string length (if NAM$L_RSA and NAM$B_RSS are 
both nonzero on input, the resultant file specification is copied 
to the buffer specified by NAM$L_RSA). 

This field is not supported for DECnet operations. 

RETURN The following condition values are described in Appendix A: 
VALUES RMS$_ACS RMS$_BLN RMS$_BUG_DAP RMS$_BUG_DDI 

RMS$_CDA RMS$_CHN RMS$_DEV RMS$_DIR 

RMS$_DME RMS$_DNA RMS$_DNF RMS$_DNR 

RMS$_DVI RMS$_ESA RMS$_ESS RMS$_FAB 

RMS$_FNF RMS$_FNM RMS$_IFI RMS$_IOP 

RMS$_LNE RMS$_MKD RMS$_NAM RMS$_NET 

RMS$_NETFAIL RMS$_NOD RMS$_NORMAL RMS$_PRV 

RMS$_QUO RMS$_RLF RMS$_RSS RMS$_RST 

RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPERSEDE 

RMS$_SUPPORT RMS$_SYN RMS$_TYP RMS$_VER 

RMS$_WLK 
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The Extend service increases the amount of space allocated to a VMS 
RMS disk file. This service is most useful for extending relative files and 
indexed files when you are doing block I/O transfers using the Write 
service. 











FORMAT SYS$EXTEND fab |, [err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Extend service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


suc 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 
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The Extend service is performed automatically as data is written to a file, 
regardless of the file’s organization. However, when you use block I/O, only 
sequential files are automatically extended. Thus, you must use the Extend 
service for relative and indexed files when using block I/O. Also, you may 
want to extend a file explicitly for performance reasons, such as placing a 
large file extent (an extended part of a file) contiguous with the file. 


You must open the file (FABSW_IFI must not be 0) before you invoke the 
Extend service; otherwise, an error occurs. The file sharing field (FAB$B_ 
FAC) must specify put (FAB$V_PUT) or update (FAB$V_UPD) access to the 
file to be extended. 


The allocation quantity field (FAB$L_ALQ or XAB$L_—ALQ) specifies the 
number of blocks that VMS RMS adds to the file. You can indicate other 
attributes regarding the manner and location for allocation. For example, you 
can indicate that the additional blocks must be allocated contiguously. If you 
do specify contiguous space and not enough contiguous space is available, the 
operation fails. (This extension is not contiguous with the initial file space.) 


If an allocation control XAB is present, its allocation quantity (XAB$L_ALQ) 
and allocation options (XAB$B_AOP, XAB$V_CBT and XAB$V_CTG bits 
only) fields are used instead of the corresponding fields in the FAB. The 
allocation quantity field of the XAB is set to the actual extension size. You 
may specify multiple XABs to extend separate areas of indexed files. 


Table RMS-19 lists the control block fields read as input by the Extend 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS-19_ Extend Service FAB Input Fields 


Field Name Description 


FAB$L_ALO Allocation quantity; ignored if an allocation XAB is present. 


FAB$L_FOP File-processing options: checked to see whether the FABSV_ 
CTG or FAB$V_CBT bit is set to indicate contiguous allocation 
(ignored for allocation XAB). 


FAB$SW_IFI Internal file identifier (must not be O). 


FAB$L_XAB Extended attribute block address. Only an allocation XAB 
(XABALL) is processed. 


Table RMS-20 lists the control block fields written as output by the Extend 
service. 


Table RMS-—20 Extend Service FAB Output Fields 


Field Name Description 

FAB$L_ALOQ Allocation quantity: contains the actual extension allocation 
value if no allocation XAB is present. 

FAB$L_STS Completion status code (also returned in register QO). 

FAB$L_STV Status value (contains the total number of blocks allocated, 


totaled across all allocation XABs). 
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RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_AID RMS$_ALN RMS$_ALO 
RMS$_AOP RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BUG_DAP RMS$_CDA RMS$_COD RMS$_DME 
RMS$_EXT RMS$_FAB RMS$_FAC RMS$_FUL 
RMS$_IFI RMS$_IMX RMS$_IOP RMS$_LEX 
RMS$_NET RMS$_NETFAIL RMS$_NORMAL RMS$_PLG 
RMS$_RPL RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_WBE RMS$_WER 
RMS$_WLK RMS$_WPL RMS$_XAB 
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The Find service locates a specified record in a file and returns its record 
file address in the RAB$W_RFA field of the RAB. The Find service can be 
used with all file organizations. 











FORMAT SYS$FIND rab |, [err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Find service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast—procedure 

type: procedure entry mask 
access: cali without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUuC 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Find service gives you the following functional capabilities: 


e You can skip records when you are accessing a file sequentially by 
making successive invocations of the Find service. 


¢ You can establish the current record context prior to invoking an Update, 
Delete, or Truncate service. 


e You can establish a random access starting point in a, file for subsequent 
sequential access operations such as the Get service. 


When you follow the Find service with a sequential access operation, such as 
the Get service, the current record context is established by the Find service 
and the sequential access operation establishes a new sequential access context. 
Conversely, when you follow the Find service with a nonsequential access 
operation such as a Delete service or an Update service, the sequential access 
context remains the same as it was prior to the Find service. 


Table RMS-21 lists the control block fields read as input by the Find service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—21 Find Service RAB Input Fields 





Field Name XAB Type Description 
RAB$SW_JISI internal stream identifier (required). 
RAB$L_KBF Key buffer address (used only if RAB$B_ 


RAC field contains RAB$SC_KEY or if 
RAB$B_RAC contains RAB$C_SEQ and the 
RAB$L_ROP field RAB$V_LIM option is 


set). 

RAB$B_KRF Key of reference (used only with indexed 
files and if RAB$B_RAC contains RAB$C_ 
KEY). 

RAB$B_KSZ Key size (used only if RAB$B_RAC field 


contains RAB$C_KEY or if RAB$B_RAC 
contains RAB$C_SEQO and the RAB$L_ROP 
field RAB$V_LIM option is set). 


RAB$L _PBF' Prompt buffer address (applies to terminal 
devices only). 


RAB$B_PSZ' Prompt buffer size (applies to terminal 
devices only). 

RAB$B_RAC Record access mode (RAB$C_SEQ, 
RAB$C_KEY, RAB$C_RFA)?. 

RABSW_RFA Record file address (used only if RAB$B_ 
RAC contains RAB$C_RFA). 

RAB$L __ROP Record-processing options. 


RAB$SV_ASY Asynchronous: performs Find services 
asynchronously. 


'This field is not supported for DECnet operations. 
2The default for the RAB$B_RAC field is RAB$C_SEQ. 
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Table RMS-—21 (Cont.) Find Service RAB Input Fields 


Field Name 


XAB Type 
RAB$SV_CVT' 


RAB$V_KGE? 


RAB$V_KGT‘ 


RABS$V_LIM 


RABSV_NLK 


RAB$V_NXR 


RABSV_PMT' 


RABSV_PTA' 


RABSV_RAH' 


RAB$SV_REA 


RABSV_RLK 


RABS$V_RNE' 


RAB$V_RNEF' 


RAB$V_RRL 


Description 


Convert: changes characters to uppercase 
for a Find service to a terminal device. 


Key is greater than or equal to compared 
value (applies only to indexed files). 


Key is greater than compared value (applies 
only to indexed files). If neither RABSV_ 
KGE nor RAB$V_KGT is specified, a key 
equal match is made. 


Limit: the key value described by the KBF 
and KSZ fields is to be compared to the 
value in the record accessed sequentially. 


No lock: specifies that the record accessed 
through the Find service is not to be locked. 


Nonexistent record processing: specifies 
that if the record directly accessed through 
a Find service does not exist, the service is 
to be performed anyway. 


Prompt indicates that the contents of the 
prompt buffer are to be used as a prompt 
for a Find service to a terminal device. 


Purge type-ahead buffer: eliminates any 
information that may be in the type-ahead 
buffer for a Find service to a terminal 
device. 


Read ahead: used with multiple buffers to 
indicate read-ahead operations (Sequential 
files only). 


Lock for read: allows other users read 
access to the record. 


Read of locked record allowed: specifies 
that a user who locks a record is allowing 
the locked record to be read by other 
accessors. 


Read no echo: indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 


Read no filter: indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered control commands on terminal 
input, but are to be passed to the | 
application program. 


Read regardless of lock: read the record 
even if another stream has locked the 
record. 


'This field is not supported for DECnet operations. 


3This symbolic offset is logically synonymous with RAB$V_EQNXT. 


4This symbolic offset is logically synonymous with RAB$V_NXT. 
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Table RMS-21 (Cont.) Find Service RAB Input Fields 


Field Name XAB Type 
RAB$V_TMO' 
RAB$V_ULK 
RAB$SV_WAT 
RAB$B_TMO' 


Description 


Timeout: indicates that the contents of 
the timeout period field (RAB$B_TMO) is 
to be used on a Find request for a locked 
record (when the RAB$V_WAT option is 
also specified) or for a terminal or mailbox 
device. 


Manual unlocking: specifies that a record 
cannot be automatically unlocked. 


Wait: if record is locked, wait until it is 
available. 


Timeout period: indicates the maximum 
number of seconds that VMS RMS can use 
to complete a Find request. 


'This field is not supported for DECnet operations. 


Table RMS-22 lists the control block fields written as output by the Find 


service. 


Table RMS—22 Find Service RAB Output Fields 


Field Name Description 


RAB$L_BKT Bucket code: set to the relative record number for relative files 


accessed sequentially. 


RABSW_RFA Record file address 


RAB$L_STS Completion status code (also returned in register OQ). 


RAB$L_STV Status value. 


The record address (RAB$L__RBF) field and the record size (RABSW_RSZ) 
field are undefined after a Find service. 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT RMS$_ANI RMS$_ATR 
RMS$_ATW RMS$_BES RMS$_BLN 
RMS$_BUG RMS$_BUG_DAP RMS$_CDA 
RMS$_CHK RMS$_CONTROLC RMS$_CONTROLY 
RMS$_DEADLOCK RMS$_DEL RMS$_DME 
RMS$_DNR RMS$_EOF RMS$_EXENOLM 
RMS$_FAC RMS$_FTM RMS$_IBF 
RMS$_IOP RMS$_IRC RMS$_ISI 
RMS$_KBF RMS$_KEY RMS$_KRF 
RMS$_KSZ RMS$_MRN RMS$_NET 
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RMS$_NETFAIL 
RMS$_OK_DEL 
RMS$_OK __RNF 
RMS$_PBF 
RMS$_PLG 
RMS$_REF 
RMS$_RHB 
RMS$_ROP 
RMS$_RSA 
RMS$_SUC 
RMS$_SYS 
RMS$_WBE 


RMS$_NORMAL 
RMS$_OK_LIM 
RMS$_OK_RRL 
RMS$_PENDING 
RMS$_RAB 
RMS$_RER 
RMS$_RLK 
RMS$_RPL 
RMS$_SQO 
RMS$_SUP 
RMS$_TMO 
RMS$_WER 


RMS$_OK_ALK 
RMS$_OK_RLK 
RMS$_OK_WAT 
RMS$_PES 
RMS$_RAC 
RMS$_RFA 
RMS$_RNF 
RMS$_RRV 
RMS$_STR 
RMS$_SUPPORT 
RMS$_TRE 
RMS$_WLK 
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The Flush service writes out all modified |/O buffers and file attributes 
associated with the file. This ensures that all record activity up to the 
point at which the Flush service executes is actually reflected in the file. 











FORMAT SYS$FLUSH rab [,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Flush service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Flush service is not required at any time, not even with a Close service, 
because the Close service performs the Flush functions implicitly. 
During asynchronous operations, you must wait for any I/O activity to 
complete before issuing a Flush service. You can also issue a Flush service 
after receiving notification of completion through an asynchronous system 
trap (AST). 
Table RMS~23 lists the control block fields read as input by the Flush service. 
For additional information on the fields accessed by this service, see Part II. 
Table RMS—23 Flush Service RAB Input Fields 
Field Name Description 
RAB$W_ISI Internal stream identifier (required). 
RAB$L__ROP Record-processing option: RAB$V_ASY only. Asynchronous: 

performs Fiush services asynchronously. 

Table RMS-24 lists the control block fields written as output by the Flush 
service. 
Table RMS-—24_ Flush Service RAB Output Fields 
Field Name Description 
RAB$L_STS Completion status code (also returned in register 0). 
RAB$L_STV Additional status information. 

RETUR The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BUG._DAP RMS$_CDA RMS$_DME RMS$_DNR 
RMS$_ISI! RMS$_NET RMS$_NETFAIL RMS$_NORMAL 
RMS$_PENDING RMS$_RAB RMS$_RSA RMS$_STR 
RMS$_SUC RMS$_SUP RMS$_SUPPORT RMS$_SYS 
RMS$_WBE RMS$_WER RMS$_WLK 
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The Free service unlocks all records that were previously locked for the 
record stream. 











FORMAT SYS$FREE rab /[,/err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Free service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Free service unlocks all records previously locked for the record stream 
(see also $RELEASE). If no records are locked for the record stream, VMS 
RMS returns a status code of RMS$_RNL. 


Table RMS-—25 lists the control block fields read as input and written as 
output by the Free service. For additional information on the fields accessed 
by this service, see Part II. . 


Table RMS-—25 Free Service RAB Input and Output Fields 


Field 
Use Name Description 
Input RAB$SW_ISI Internal stream identifier (required). 
Output RAB$L_STS Completion status code (also returned in register O). 


RAB$L_STV Status value. 





RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG_DAP RMS$_ISI 
RMS$_NET RMS$_NETFAIL RMS$_NORMAL RMS$_PENDING 
RMS$_RAB RMS$_RNL RMS$_RSA RMS$_STR 
RMS$_SUC RMS$_SUP RMS$_SUPPORT 
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The Get service retrieves a record from a file. 


Note: When you invoke the GET service, RMS takes control of the record buffer 


and may modify it. RMS returns the record size and only guarantees the 
contents from where it accessed the record to the completion of the record. 











FORMAT SYS$GET rab /,[err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Get service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 
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The Get service is performed by using one of three possible record access 
modes, as specified by the record access (RAB$B_RAC) field. The three 
record access modes are sequential (SEQ), which is the default, random by 
key (KEY), and random by record file address (RFA). 


Relevant Record Access Modes 


The sequential access mode is relevant for all file organizations as well as for 
all devices. It is the only access mode allowed for nondisk devices, such as 
terminals, mailboxes, and magnetic tape devices. In this mode, records are 
retrieved from a given file in the same order in which they were written to 
that file. This is not the case, however, for records retrieved from indexed 
files. Sequential Get services for indexed files return records by key value in 
the specified sort order, ascending or descending. The next record’s key of 
reference for sequential access to indexed files is established by one of the 
following services: 


¢ Connect 
e Rewind (see $REWIND) 
¢ Find or Get using random access by key 


¢ Find or Get using random access by RFA 


When you use random access by key with any operations related to these 
services, the key of reference is established by the key of reference field 
(RAB$B_KRF). When you use random access by RFA in conjunction with a 
Find or Get service, however, the key of reference is always set to the primary 
key. 


You can use random access by key to retrieve records by key value. For 
relative files and sequential files having fixed-length records, the key value 
is the relative record number. For indexed files, the key value depends on 
the data type of the specified key of reference. The key value is used to 
search the index of the specified key of reference to locate the desired record. 
A random access by key also establishes the next record for subsequent 
sequential retrieval. This type of access may be used in this way to establish 
a starting point for sequential retrieval of records at other than the beginning 
of the file. 


You can use random access by RFA to retrieve records directly from files 
residing on disk devices. However, a record’s address can be determined only 
if the record has been accessed previously. The Find, Get, and Put services 
each return the RFA value as output in the RAB$W_RFA field. 


Random access of records in a file is prohibited when you open the file and 
select the FAB$V_SQO option; that is, if you specify sequential operations 
only. 


Input from Stream Format Files 


For stream format files, VMS RMS fills the user buffer with data until a 
terminator is reached. If the buffer fills before a terminator is encountered, 
the remainder of the data preceding the terminator is discarded, and an 
RMS$_RTB error is returned. If the terminator for stream format (FAB$B_ 
RFM contains FAB$C_STM) is not CRLF (carriage return followed by line 
feed), the terminator is stored in the buffer following the record and included 
in the size of the record. 
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Input from Terminal Devices 
There are two methods of obtaining input from a terminal using VMS RMS: 


1 Using the RAB$L_ROP field to define the terminal input operation. 
Certain options applicable to the RAB$L_ROP field are used for terminal 
device input, such as whether a prompt is to be displayed and whether 
a time limit between characters is enforced. These options may require 
certain information to be placed in other fields of the RAB (see Chapter 7). 
The maximum buffer size is 512 bytes. 


2 Using an item list to define the terminal input operation in conjunction 
with a terminal XAB (XABTRM). The ETO option of the RAB$L_ROP 
field must be set and the user must provide an item list in the calling 
program, which VMS RMS passes to the terminal driver using the item 
list address and length specified in the XABTRM (see Chapter 18). This 
method allows use of any terminal input option supported by the terminal 
driver, in contrast to the subset of RAB$L_ROP options available using 
the other method. The maximum buffer size is 512 bytes. 


VMS RMS uses the standard terminator set when performing input operations 
from terminal devices. The second longword of the I/O status block used 

is returned in the RAB$L_STV field. The terminating character is returned 
in the lower word of the status value field (RABSW_STV0); however, note 
that with extended terminal operations, the terminating character is in the 
first byte of RABSW_STVO, not in the entire RAB$W_STVO word. More 
information about the second longword of the I/O status block is available in 
the VMS I/O User’s Reference Manual: Part I in the VMS I/O User’s Reference 
Volume. The RAB$W_STV0 field is device dependent for terminal devices. 


The CTRL/Z character terminates the Get service and acts as an end-of-file 
marker for VMS RMS. If you enter a CTRL/Z in response to a request for 
data, VMS RMS returns the completion status code for end-of-file (RMS$_ 
EOF). VMS RMS takes the data you enter before the CTRL/Z but the next 
Get service returns a single end-of-file error (RMS$_EOF) without accepting 
any further input from the device. VMS RMS resumes taking input if you 
request a subsequent Get service. 


VMS RMS also supports the use of escape sequences from terminal devices 
that are accessed locally and have escape sequences enabled. Escape 
sequences for a terminal are enabled by the SET TERMINAL command 
(described in the VMS DCL Dictionary). Escape sequences are returned in the 
record buffer. The record size (RAB$W_RSZ) is the offset within the buffer 
(RAB$L_RBF) to the beginning of the escape sequence. The high-order word 
of the status value field (RABSW_STV2) contains the length of the escape 
sequence, except for extended terminal operations. In this case, the escape 
sequence length is returned in the first byte of RAB6W_STV2, not the entire 
RAB$W_STV2 word, and the terminator position is returned in the second 
byte of the RABSW_STV2 word. When a partial escape sequence warning 
(RMS$_PES) is returned, the remaining characters in the escape sequence are 
returned by the next read request from the terminal. 


RMS-—49 


VMS RMS Services 


$GET 


RMS-—50 


Input from Mailbox Devices 


Mailboxes may be used to synchronize activity across cooperating processes. 
Normally, a Get service from a mailbox device is not completed until a record 
is present in the mailbox. When the Get service is completed, the status value 
field (RAB$L_STV) contains the process identification (PID) of the process 
that put the record into the mailbox. However, if the timeout (TMO) record 
option is specified with a value of 0 in the timeout field and if no messages 
are present in the mailbox, then the Get service returns an end-of-file error 
(RMS$_EOF). This technique assures your process of an immediate return, 
whether or not messages are present in the mailbox. 


Using the RAB$L_STV Field 


The RAB$L_STV field contains additional status information for a number of 
situations. When the completion status is a record-too-big warning (RMS$_ 
RTB), RAB$L_STV contains the total record size. For record-oriented devices 
such as terminals and mailboxes, the second longword of the I/O status 
block is returned in the RAB$L_STV field, whenever the completion status 
(RAB$L_STS) is a success code. The alternate field definitions of RAB$W_ 
STVO and RABS$W_STV2 are provided to reference the respective low- and 
high-order words of the RAB$L—STV field. The record size field (RABSW_ 
RSZ) always reports the amount of data returned, regardless of the completion 
status (RAB$L_STS). The presence of valid data on error conditions may then 
be detected by checking the record size field. 


The User Record Area 


The Get service always requires the presence of a user record area, as 
specified by the user record buffer address (RAB$L_UBF) and user buffer 
area size (RAB$W_USZ) fields in the RAB. 


For undefined format files, the RAB$W_USZ field defines the amount of data 
to be returned on each Get service. 


Table RMS-26 lists the control block fields read as input by the Get service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-26 Get Service RAB Input Fields 


Option or 

Field Name XAB Type Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$L_KBF Key buffer address: used only if the 
RABS$B_RAC field contains RAB$C_KEY, 
or if the RAB$B_RAC field contains 
RAB$C_SEOQ and you select the RAB$V_ 
LIM option. 

RAB$B_KRF Key of reference: used only with indexed 


files and only if the RABSB_RAC field 
contains RAB$C_KEY. 


RAB$B_KSZ Key buffer size: used only if the RAB$B_ 
RAC field contains RAB$C_KEY, or if the 
RABS$B_RAC field contains RAB$C_SEQ 
and you select the RAB$V_LIM option. 


Table RMS—26 (Cont.) 


Field Name 
RABS$L_PBF' 


RAB$B_PSZ' 
RAB$B_RAC 
RABSW_RFA 
RAB$L_RHB 


RAB$L_ROP 


Option or 
XAB Type 


RAB$V_ASY 


RAB$V_CVT' 


RAB$V_ETO' 


RAB$V_KGE® 


RAB$V_KGT* 


RABS$V_LIM 


RAB$V_LOC'! 


RAB$V_NLK 
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Get Service RAB Input Fields 


Description 


Prompt buffer address (applies to 
terminal devices only). 


Prompt buffer size (applies to terminal 
devices only). 


Record access mode (RAB$C_SEQ, 
RAB$C_KEY, RAB$C_RFA).” 


Record file address: used only if the 
RAB$B_RAC field contains RAB$C_RFA. 


Record header buffer: used for the 
fixed-length control area of VFC records. 


Record-processing options. 


Asynchronous: performs Get services 
asynchronously. 


Convert: changes characters to 
uppercase for a Get service to a terminal 
device. 


Extended terminal operation: specifies 
that an XABTRM and an item list 

are used to define the terminal input 
operation. If this option is specified, no 
other RAB$SL_ROP options applicable to 
terminal devices can be used. 


Search for equal key value or next key 
value according to sort order (applies 
only to indexed files). 


Search for next key value according to 
sort order; if neither the RAB$V_KGE 
(RAB$V_EQNXT) option nor the RAB$SV__ 
KGT (RAB$V_NXT) option is specified, 
VMS RMS looks for a key match. 


Limit: specifies that the key value 
described by the RAB$L_KBF field and 
the RAB$B_KSZ field is to be compared 
with the value in the record accessed 
sequentially. 


Locate mode: specifies that Get service 
record operations use locate mode. 


No lock: specifies that the record 
accessed through the Get service is 
not to be locked. 


\This field is not supported for DECnet operations. 
?The default for the RAB$B_RAC field is RAB$C_SEQ. 
3This symbolic offset is logically synonymous with RAB$V_EONXT. 


4This symbolic offset is logically synonymous with RAB$V_NXT. 
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Table RMS-26 (Cont.) Get Service RAB Input Fields 


Field Name 


Option or 
XAB Type 


RAB$V_NXR 


RAB$V_PMT' 


RAB$V_PTA' 


RAB$V_RAH' 


RAB$V_REA 


RAB$V_RLK 


RAB$V_RNE' 


RAB$V_RNF' 


RAB$V_RRL 


RAB$V_TMO'! 


RAB$V_ULK 


RABSV_WAT 


Description 


Nonexistent record processing: specifies 
that if the record directly accessed 
through a Get service does not exist, the 
service is to be performed anyway. 


Prompt: indicates that the contents of 
the prompt buffer are to be used as a 
prompt on a Get service to a terminal 
device. 


Purge type-ahead: eliminates any 
information that may be in the type- 
ahead buffer, on a Get service to a 
terminal device. 


Read ahead: used with multiple buffers 
to indicate read-ahead operations 
(sequential files only). 


Lock for read: allows other users read 
access to the record. 


Read of locked record allowed: specifies 
that a user who locks a record for 
modification is allowing the locked record 
to be read by other accessors. 


Read no echo indicates that input data 
entered on the keyboard is not echoed 
(displayed) on the terminal device. 


Read no filter: indicates that CTRL/U, 
CTRL/R, and DELETE are not to be 
considered contro! commands on 
terminal input, but are to be passed 
to the application program. 


Read regardless of lock: read the record 
even if another stream has locked the 
record. 


Timeout: indicates that the content of 
the timeout period field (RAB$B_TMO) is 
to be used. 


Manual unlocking: specifies that records 
cannot be automatically unlocked. 


Wait: if record is locked, wait until it is 
available. 


'This field is not supported for DECnet operations. 
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Table RMS—26 (Cont.) Get Service RAB Input Fields 


Option or 
Field Name XAB Type 
RAB$B_TMO! 
RABSL__UBF 
RAB$W_USZ 
RAB$L_XAB XABTRM' 


Description 


Timeout period: indicates the maximum 
number of seconds that VMS RMS 
allows between characters for a Get 
service to terminal and mailbox devices 
only, or the maximum number of seconds 
VMS RMS waits for a locked record 

if you specify the RAB$V_TMO and 
RAB$V_WAT options in the RABSL_— 
ROP field. 


User record buffer address (required). 
User record buffer size (required). 

Next XAB address: indicates the address 
of an XABTRM control block (the 
RABSL_ROP field RAB$V_ETO option 


must be set for an extended terminal 
operation). 


This field is not supported for DECnet operations. 


Table RMS-—27 lists the control block fields written as output by the Get 


service. 


Table RMS-27 Get Service RAB Output Fields 


Field Name Description 


RAB$L_BKT Bucket code: set to the relative record number for relative files 
when the record access mode is sequential. 


RABS$L_RBF Record buffer address. 


RABSW_RFA Record file address. 


RABSW_RSZ Record size. 


RAB$L_STS Completion status code (also returned in register 0). 


RAB$L_STV Status value (contains a terminator character for terminal input 
or the record length if the requested record is too large for the 


user buffer area). 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT RMS$_ANI RMS$_BES 
RMS$_BLN RMS$_BUG RMS$_BUG_DAP 
RMS$_CDA RMS$_CHK RMS$_CONTROLC 
RMS$_CONTROLY RMS$_DEADLOCK RMS$_DEL 
RMS$_DME RMS$_DNR RMS$_EOF 
RMS$_ENO. RMS$_EXENQLM RMS$_EXP 
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RMS$_FAC 
RMS$_IOP 

RMS$_KBF 
RMS$_KSZ 


RMS$_NETFAIL 
RMS$_OK__DEL 
RMS$_OK__RNF 


RMS$_PBF 
RMS$_PLG 
RMS$_RER 
RMS$_RLK 
RMS$_RPL 
RMS$_RTB 
RMS$_SUC 
RMS$_SYS 
RMS$_TRE 
RMS$_WER 


RMS$_FTM 
RMS$_IRC 
RMS$_KEY 
RMS$_MRN 
RMS$_NORMAL 
RMS$_OK_LIM 
RMS$_OK_RRL 
RMS$_PENDING 
RMS$_RAB 
RMS$_RFA 
RMS$_RNF 
RMS$_RRV 
RMS$_SQO 
RMS$_SUP 
RMS$_TMO 
RMS$_UBF 
RMS$_WLK 


RMS$_IBF 
RMS$_ISI 
RMS$_KRF 
RMS$_NET 
RMS$_OK_ALK 
RMS$_OK_RLK 
RMS$_OK_WAT 
RMS$_PES 
RMS$_RAC 
RMS$_RHB 
RMS$_ROP 
RMS$_RSA 
RMS$_STR 
RMS$_SUPPORT 
RMS$_TNS 
RMS$_WBE 
RMS$_XAB 


$NXTVOL 
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The Next Volume service allows you to process the next tape volume in 
a multiple volume set. This service applies only to files on magnetic tape 
volumes. 











FORMAT SYS$NXTVOL rab |, [err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Next Volume service call. The rab argument is the address of the RAB 
control block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 
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You use the Next Volume service when you want to proceed to the next 
volume in the set before the end of the current volume (EOV label) is reached 
on input, or before the end-of-tape (EOT) mark is reached on output. VMS 
RMS positions your process to the first file section on the next volume. File 
sections occur when a file is written on more than one volume, the portion of 
the file on each of the volumes constituting a file section. 


When you perform a Next Volume service for input files, VMS RMS responds 
as follows. 


e If the current volume is the last volume of the set, VMS RMS reports 
end-of-file information. 


e If another file section exists, the next volume is mounted. When 
necessary, the current volume is rewound and a request to mount the 
next volume is issued to the operator. 


e¢ The header label (HDR1) of the file section on the newly mounted volume 
is read. If this is not the volume being sought, the operator is requested 
to mount the correct volume. 


When you perform a Next Volume service for output files, the following 
sequence occurs: 


1 The file section on the current volume is closed with the appropriate 
end-of-volume labels, and the volume is rewound. 


2 The next volume is mounted. 


3 A file with the same file name and the next higher file section number is 
opened for output, and processing continues. 


If your program is operating asynchronously, it must wait for any I/O activity 
on this volume to complete before issuing a Next Volume service. 


The Next Volume service performs a Flush service for write-accessed volumes 
(see $FLUSH), thus writing the I/O buffers on the current volume before 
creating the next file section. If this is an input-only file, then all records 
currently contained in the I/O buffers are lost, and the next Get service 
returns the first record on the next volume. 


The Next Volume service is not supported for DECnet operations for remote 
file access between two VMS systems. 


Table RMS-28 lists the control block fields read as input and written as 
output by the Next Volume service. For additional information on the fields 
accessed by this service, see Part II. 


Use Field Name 

Input RAB$W_1ISI 
RAB$L_ROP 

Output RAB$L_STS 
RAB$L_STV 
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Table RMS—28 Next Volume Service RAB Input and Output Fields 


Description 


Internal stream identifier (required). 


Record-processing option, RAB$V_ASY. 
Asynchronous only: performs Next Volume service 
asynchronously. 


Completion status code (also returned in 
register 0). 


Status value. 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT RMS$_BLN RMS$_CDA RMS$_DME 
RMS$_DNR RMS$_DPE RMS$_IOP RMS$_ISI 
RMS$_NORMAL RMS$_PENDING RMS$_RAB RMS$_RSA 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 
RMS$_SYS 
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SOPEN 


The Open service makes an existing file available for processing by your 
program. The Open service specifies the type of record access to be used 
and determines whether or not the file can be shared. The Open service 
also performs an implicit Display service. 











FORMAT SYSSOPEN fab/|,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L__STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Open service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


You must open a file to perform any record operations and most file 
operations. If any XABs are chained to the FAB, VMS RMS places the 
attribute values in the fields of the appropriate XAB. If you specify a NAM 
block in the FAB, the contents of the device, directory, and file identification 
fields can be used with the open-by-NAM-block option to open the file. The 
NAM block fields are filled in with auxiliary file specification information. 


Table RMS-29 lists the control block fields read as input by the Open service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-—29 Open Service FAB and XAB Input Fields 


Option or 

Field Name XAB type 

FAB$V_CHAN_MODE?® 

FAB$W_DEO 

FAB$L_DNA 

FAB$B_DNS 

FAB$B_FAC 
FAB$V_BIO 
FAB$V_BRO 
FAB$V_DEL 
FAB$V_GET! 
FAB$V_PUT 
FAB$V_TRN 
FAB$V_UPD 

FABSL_FNA? 

FAB$B_FNS? 

FAB$L_FOP 
FAB$V_DFW? 
FAB$V_DLT 
FABSV_NAM? 


'This is the default value supplied by VMS RMS. 
2These fields must be specified by the user. 


3This field is not supported for DECnet operations. 


Description 


Channel access mode assignment. 


Default file extension quantity: if 

a nonzero value is present in this 
field, it applies only to this open of 
the file. 


Default file specification string 
address. 


Default file specification string size. 
File access field. 

Block I/O access. 

Block or record 1/O. 

Delete access. 

Read access. 

Write access. 

Truncate access. 

Update access. 

File specification string address. 
File specification string size. 
File-processing options. 


Deferred write: indicates that 
writing back to the file from the 
modified buffer is deferred (applies 
to relative and indexed files only). 


Delete: indicates the file is to be 
deleted when it is closed. 


Name block inputs: indicates that 
the NAM$W_FID, NAM$W__DID, 
and NAM$T_DVI fields in the 
specified NAM block are to be 
used to describe the file. 
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Table RMS—29 (Cont.) Open Service FAB and XAB Input Fields 


Option or 
Field Name XAB type 


FAB$V_NFS? 


FABSV_OFP 


FAB$V_RCK 


FABSV_RWC 
FAB$V_RWO 


FAB$V_SCF? 


FAB$V_SPL? 


FABSV_SOQO 


FAB$V_TEF 


FAB$V_UFO? 


FAB$V_WCK 


FAB$B_FSZ 


FABSW_IFI 


3This field is not supported for DECnet operations. 


Description 


Non-file-structured: indicates that 
the accessed volume is to be 
processed in a non-file-structured 
manner. 


Output file parse: specifies that 
the related file resultant file 
specification string, if used, is 

to provide file name and file type 
defaults only. 


Read-check: indicates that transfers 
from disk are to be checked by a 
followup, read-compare operation. 


Rewind on close (applies to 
magnetic tapes only). 


Rewind on open (applies to 
magnetic tapes only). 


Submit command file: indicates 
that the file is to be submitted as a 
batch-command file to the process 
default batch queue (SYS$BATCH) 
when the file is closed (applies to 
sequential files only). 


Spool: indicates that the file is to 

be spooled to the process default 

print queue (SYS$PRINT) when the 
file is closed (applies to sequential 
files only). 


Sequential! only: indicates that 
the file can be processed in a 
sequential manner only. 


Truncate at end of file: indicates 
that unused space allocated to a 
file is to be deallocated when that 
file is closed (applies to sequential 
files only). 


User file open: indicates the file 

is to be opened only (no further 
VMS RMS processing of that file is 
allowed). 


Write-check: indicates that 
transfers to disk are to be followed 
by a read-compare operation. 


Fixed control area size: unit record 
devices only. 


Internal file identifier (must be Q). 
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Table RMS-—29 (Cont.) Open Service FAB and XAB Input Fields 


Option or 


Field Name XAB type 


FAB$V_LNM_MODE? 


FAB$L_NAM 

FAB$B_RAT 

FAB$B_RFM 

FAB$B_RTV? 

FAB$B_SHR 
FAB$V_SHRDEL 
FAB$V_SHRGET 
FAB$V_MSE? 
FABSV_NIL 
FAB$V_SHRPUT 
FAB$V_SHRUPD 
FAB$V_UPI 

FAB$L_XAB* 
XABITM 


Description 

Specifies the logical name 
translation access mode. 
Name block address. 


Record attributes; only for process 
permanent files with print file 
format. 


Record format; unit record devices 
only. 


Retrieval window size. 
File-sharing field. 
Shared delete access. 
Shared read access. 


Multistream access; also used with 
the FAB$V_MSE and FAB$V_GET 
bits to specify a read-only global 
buffer cache when global buffering 
is enabled. 


No shared access. 
Shared write access. 
Shared update access. 


Shared write access for block I/O 
(applies to sequential files only). 


Extended attribute block address. 
Item list XAB; see Chapter 11. 


3This field is not supported for DECnet operations. 


4The appropriate XAB must be specified as input if you desire information about that 


particular XAB on output from the Open Service. 


Table RMS-30 lists the control block fields written as output by the Open 


service. 


Table RMS—30 Open Service FAB and XAB Output Fields 


Description 


Allocation quantity: contains the highest 


numbered block allocated to the file. 


Option or 
Field Name XAB Type 
FAB$L_ALO 
FAB$B_BKS 
FABSW_BLS 
FABSW_DEO 


Bucket size (does not apply to sequential 
files). 


Device block size (applies only to sequential 
files). 


Default file extension quantity. 
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Table RMS-—30 (Cont.) Open Service FAB and XAB Output Fields 


Field Name 
FAB$L_DEV 
FAB$B_FAC 
FAB$L_FOP 


FAB$B_FSZ 


FAB$W_GBC 
FABSW_IFI 
FABSL_MRN 


FAB$W_MRS 
FAB$B_ORG 
FAB$B_RAT 


FAB$B_RFM 
FAB$L_SDC 
FAB$B_SHR 
FAB$L_STS 


FAB$L_STV 


FABSL_XAB 


Option or 
XAB Type 


FAB$V_CBT 


FAB$SV_CTG 
FAB$V_RCK 


FAB$V_WCK 


XABALL 
XABDAT 
XABFHC 


XABITM 
XABKEY 
XABPRO 
XABRDT 
XABSUM 


Description 

Device characteristics. 
File access. 
File-processing options. 


Contiguous best try: indicates that the file 
is allocated contiguously on a “best effort” 
basis. — 


Contiguous: indicates that space for the file 
is allocated contiguously. 


Read-check: transfers are followed up by a 
read-compare operation. 


Write-check: transfers are followed up by a 
read-compare operation. 


Fixed-length control area size (applies only to 
VFC records). 


Global buffer count. 
Internal file identifier. 


Maximum record number (for relative files 
only). 


Maximum record size. 
File organization. 


Record attributes; used as output field except 
for process-permanent files with print file 
format. 


Record format. 
Spooling device characteristics. 
File sharing. 


Completion status code (also returned in 
register QO). 


Status value (contains the I/O channel 
number if the operation is successful). 


Next XAB address. 
Allocation XAB; see Chapter 8. 
Date and time XAB; see Chapter 9. 


File header characteristics XAB; see 
Chapter 10. 


Item list XAB; see Chapter 11. 

Key definition XAB; see Chapter 13. 
Protection XAB; see Chapter 14. 

Revision date and time XAB; see Chapter 15. 
Summary XAB; see Chapter 17. 
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Using the Name Block for Opening Files 


Table RMS-31 and Table RMS-32 list the NAM block fields (further described 
in Chapter 6) used as input and output for the Open service (provided that 
the NAM block address field is specified in the FAB). 


Table RMS-—31 Open Service NAM Block Input Fields 


Field Name Option 
NAM$W_DID' 


NAM$T_DvI' 


NAMS$L_ESA 
NAM$B_ESS 
NAM$W_FID' 


NAM$B_NOP 
NAM$V_PWD 


NAM$V_NOCONCEAL 


NAMS$L __RLF 
NAM$B_RSL 
NAMS$L_RSA 
NAMS$L __FNB 

NAM$L_RSA 

NAM$B_RSS 


Description 


Directory identification (input only if 
the FAB$L_FOP field FABSV_NAM 
option is set). 

Device identification (input only if 
the FAB$L_FOP field FAB$V_NAM 
option is set). 

Expanded string area address. 
Expanded string area size. 

File identification (input only if the 
FABS$L_FOP field FAB$V_NAM 
option ts set). 

NAM block options. 


Password: indicates that a password 
contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word “password"). 


Do not conceal device name: 
indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name in the resultant string. 


Related file NAM block address. 


Related file NAM block resultant 
string length. 


Related file NAM block resuitant 
string address. 


Related file NAM block file name 
status bits. 


Resultant string area address. 
Resultant string area size. 


'This field is not supported for DECnet operations. 
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Table RMS—32 Open Service NAM Block Output Fields 

Field Name Description 

NAM$W_DID' Directory identification. 

NAM$T_DVI' Device identification. 

NAM$B_ESL Expanded string length. If the NAM$L_ESA and NAM$B_ESS 
fields are nonzero, and if the FAB$L_FOP field FAB$V_NAM 
option is clear or the NAM$W_DID and NAM$W__FID fields 
are O on input, the expanded file specification string is copied 
to the buffer specified by the NAM$L_ESA field. 

NAM$W_FID' File identification. 

NAMS$L_FNB File name status bits. 

NAM$B_RSL Resultant string length. If the NAM$L_RSA field and the 
NAMS$B_RSS field are nonzero, and if the FAB$V_NAM bit is 
clear or the NAM$W_FID field is zero when you invoke the 
Open service, the resultant file specification is copied to the 
buffer specified by the NAM$L_RSA field. 

'This field is not supported for DECnet operations. 

The NAM block file specification string descriptors can be used to identify 

individual components of the expanded or resultant file specification. These 

fields include the following: 

e NAM$B_NODE and NAM$L_NODE 

e NAM$B_DEV and NAM$L_DEV 

¢ NAM$B_DIR and NAM$L__DIR 

e NAM$B_NAME and NAM$L_NAME 

e NAM$B_TYPE and NAM$L_TYPE 

¢ NAM$B_VER and NAM$L_VER 

For additional information about these descriptors, see Chapter 6. 

RETURN The following condition values are described in Appendix A: 
VALUES RMS$_ACC RMS$_ACS RMS$_ACT 

RMS$_ AID RMS$_ATR RMS$_BLN 

RMS$_BUG_DAP RMS$_BUG_DDI RMS$_CHN 

RMS$_COD RMS$_CRMP RMS$_DEV 

RMS$_DIR RMS$_DME RMS$_DNA 

RMS$_DNF . RMS$_DNR RMS$_DVI 

RMS$_ENO RMS$_ENV RMS$_ESA 

RMS$_ESS RMS$_EXP RMS$_FAB 

RMS$_FLK RMS$_FNA RMS$_FNF 

RMS$_FNM RMS$_FOP RMS$_IFA 
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RMS$_IF1 
RMS$_KNM 
RMS$_NAM 
RMS$_NOD 
RMS$_ORG 
RMS$_PRV 
RMS$_REF 
RMS$_RSS 
RMS$_SHR 
RMS$_SUP 
RMS$_SYN 
RMS$_UPI 
RMS$_XAB 


RMS$_IMX 
RMS$_KSI 
RMS$_NET 
RMS$_NORMAL 
RMS$_PLG 
RMS$_QUO 
RMS$_RLF 
RMS$_RST 
RMS$_STR 
RMS$_SUPERSEDE 
RMS$_SYS 
RMS$_VER 
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RMS$_IRC 
RMS$_LNE 
RMS$_NETFAIL 
RMS$_OK _NOP 
RMS$_PLV 
RMS$_RAT 
RMS$_RPL 
RMS$_RUNDOWN 
RMS$_SUC 
RMS$_SUPPORT 
RMS$_TYP 
RMS$_WLK 
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$PARSE 


The Parse service analyzes the file specification string and fills in various 
NAM block fields. 











FORMAT SYS$PARSE fab |,/err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Parse service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The functions of the Parse service are performed automatically as part of the 
Open, Create, and Erase services. One special purpose of the Parse service is 
to prepare the FAB and NAM blocks for wildcard character processing to be 
used in the Search service. If wildcard characters, search list logical names, 
or a node name are present in the file specification, VMS RMS allocates 
internal data structures (including a device channel) to store the context 

for subsequent searches. This space is released when the Search service 
encounters a no-more-files condition (in which case an RMS$_NMF error 
status is returned) or when another Parse service is performed using the same 
FAB and NAM blocks. To release this space, use a Parse service that specifies 
the NAM$B_NOP field NAM$V_SYNCHK option and sets the FAB$B_DNS 
and NAM$L_RLF fields to zero. 


Note that the file must be closed before you invoke the Parse service 
(FAB$W_IFI must be 0). 


By default, the Parse service assigns a channel to the device and does a 
lookup of the directory in addition to analyzing the file specification and 
filling in the NAM block fields. To request a Parse service without I/O, 
specify the NAM$B_NOP field NAM$V_SYNCHK option. The result of 
a Parse service without I/O cannot be used as input to subsequent Search 
services. 


Table RMS-33 and Table RMS-34 list the fields in both the FAB and NAM 
block that the Parse service uses as input and output. In addition, the string 
component descriptors are filled in by VMS RMS as output from the expanded 
string (see Chapter 6). 


The expanded file specification string is moved to the buffer described by 
the expanded string area address (NAM$L_ESA) and size (NAM$B_ESS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_ESA 
and NAM$B_ESS fields must be specified (nonzero) for wildcard character 
processing. 


Table RMS-33 lists the control block fields read as input by the Parse service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-—33 Parse Service FAB and NAM Block Input Fields 


Field Name Option Description 

FAB$L_DNA Default file specification string. 
FAB$B_.DNS Default file specification string size. 
FAB$L_FNA File specification string address. 
FAB$B_FNS File specification string size. 
FAB$L_FOP File-processing option, FAB$V_OFP. 


Output file parse: indicates that VMS 
RMS uses only the file name and file 
type fields of a related file resultant 
string whose address is contained in 
the NAM$L_RSA field. 


FAB$W_IFI Internal file identifier (must be zero). 
FAB$L_NAM Name block address. 
NAM$L_ESA Expanded string area address. 
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Table RMS-—33 (Cont.) Parse Service FAB and NAM Block Input 


Fields 
Field Name Option 


NAM$B_ESS 
NAM$B_NOP 
NAM$V_NOCONCEAL 


NAM$V_PWD 


NAM$V_SYNCHK 
NAMS$L__RLF 
NAM$L_RSA 


NAM$B_RSL 


NAMS$L__FNB 


Description 


Expanded string area size. 
NAM block options. 


Do not conceal device name: indicates 
that when a concealed device logical 
name is present, the concealed device 
logical name is to be replaced by the 
actual physical device name in the 
expanded string. 


Password: indicates that a password 
contained in a DECnet access control 
string, if present in a file specification, 
is to be left unaltered in the expanded 
and resultant strings (instead of being 
replaced by the word “password"). 


Performs Parse service with no I/O. 
Related file NAM block address. 


Related file NAM block resultant string 
area address. 


Related file NAM block resultant string 
length. 


Related file NAM block file name 
status bits. 


Table RMS-34 lists the control block fields written as output by the Parse 


service. 


Table RMS-—34 Parse Service FAB and NAM Block Output Fields 


Device characteristics (unless you select the NAM$V_ 
Secondary device characteristics (unless you select the 


Completion status code (also returned in register 0). 


Address of file specification device descriptor. 
Size of file specification device descriptor. 
Directory identification (unless you select the NAM$V_ 


Address of file specification directory descriptor. 


Field Name Description 
FAB$L_DEV 

SYNCHK option). 
FABS$L_—SDC 

NAM$V_SYNCHK option). 
FAB$L_STS 
FABSL_STV Status value. 
NAM$B_DEV 
NAMS$L _DEV 
NAM$W_DID' 

SYNCHK option). 
NAM$B_DIR 
NAMS$L_DIR 


Size of file specification directory descriptor. 


1This field is not supported for DECnet operations. 
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Table RMS—34 (Cont.) Parse Service FAB and NAM Block Output 


Field Name 
NAM$T_DVI" 


NAM$B_ESL 
NAMS$W_-FID! 
NAM$L_FNB 


NAM$B_NAME 
NAM$L_NAME 
NAMS$B_NODE 
NAM$L_NODE 
NAM$B_RSL 
NAM$B_TYPE 
NAMS$L __TYPE 
NAM$B_VERSION 
NAMS$L_VERSION 
NAMS$L_WCC 


Fields 
Description 


Device identification (unless you select the NAM$V_ 
SYNCHK option). 


Expanded string length. 
File identification (zeroed). 


File name status bits: contains information about the 
parse results. 


Address of file specification name descriptor. 
Size of file specification name descriptor. 
Address of file specification node descriptor. 
Size of file specification node descriptor. 
Resultant string length (zeroed). 

Address of file specification type descriptor. 
Size of file specification type descriptor. 
Address of file specification version descriptor. 
Size of file specification version descriptor. 
Wildcard context. 


'This field is not supported for DECnet operations. 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACS 
RMS$_CHN 
RMS$_DNA 
RMS$_ESS 
RMS$_IFI 
RMS$_NORMAL 
RMS$_STR 
RMS$_VER 


RMS$_BLN RMS$_BUG_DDI RMS$_CDA 
RMS$_DEV RMS$_DIR RMS$_DME 
RMS$_DNF RMS$_DNR RMS$_ESA 
RMS$_FAB RMS$_FNA RMS$_FNM 
RMS$_LNE RMS$_NAM RMS$_NOD 
RMS$_QUO RMS$_RLF RMS$_RUNDOWN 
RMS$_SUC RMS$_SYN RMS$_TYP 
RMS$_WCC 
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The Put service inserts a record into a file. 














FORMAT SYS$PUT rab [,/err] [, suc] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
RAB control block whose contents are to be used as indirect arguments for 
the Put service call. The rab argument is the address of the RAB control 
block. 
err 
VMS usage: ast_procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 
Suc 
VMS usage: ast_procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
DESCRIPTION The Put service usually adds records to the logical end of a sequential file. 
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For relative files, it may add records to the logical end of the file or it may 
insert new records in cells formerly occupied by deleted records. VMS RMS 
directs the Put service where to insert the record using the contents of the 
record’s primary key field. 
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Inserting Records into Sequential Files 


When using sequential record access mode to process sequential files, you 
usually insert records at the end of the file only. The records to be inserted 
cannot be larger than the maximum length that was specified when the file 
was created. 


You can use random access by relative record number mode and the update-if 
record-processing option (RAB$V_UIF) to insert fixed-length records into a 
sequential file residing on a disk device. 


VMS RMS also provides for establishing the logical end of the file when two 
or more processes are doing shared write operations. For example, assume 
that processes A and B are sharing a sequential file and each process is putting 
data into the file. Process A puts a record at the end of the file and intends to 
put another record at the new end-of-file location. However, before process A 
can put the next record in the file, process B gains access to the file and puts 
a record at the end of the file. In order to ensure that the next record from 
process A does not overwrite the record just inserted by process B, VMS RMS 
updates process A’s write pointer to the new end-of-file position. That is, the 
location immediately following the location of process B’s record. 


The truncate-on-put option (RAB$V_TPT) can be used with sequential files. 
This option lets you add records at locations other than the logical end of 
the file. When you add a record using the truncate-on-put option, the file is 
automatically truncated, effectively deleting all data between the new record 
(logical end of the file) and the physical end of the file. If you try to use this 
option without having truncate access, VMS RMS rejects the operation and 
issues a file access error (RMS$_FAC). 


For stream format files, VMS RMS writes the contents of the user’s buffer into 
the file beginning at the current entry position. If the last byte in the buffer 
is not a terminator, VMS RMS automatically adds the appropriate terminator. 
For stream format, the terminator is CRLF (carriage return character followed 
immediately by a line feed character). 


Mailboxes may be used to synchronize activity between processes. Usually, 
a Put service to a mailbox does not conclude until another accessor reads the 
record. If you select the timeout option (RAB$V_TMO) and specify a timeout 
period of 0, the Put service does not wait for another accessor to read the 
record. 


At the conclusion of the Put service, the RAB$L_STV field contains the 
process identification (PID) of the process that read the record. 


Inserting Records into Relative Files 


When processing relative files, you can use either sequential or random access 
by key mode. Records cannot be larger than the size specified at file creation 
time, and the record’s relative record number must not exceed the maximum 
record number established for the file. Usually, if the target record cell for 

a Put service contains a record, a record-already-exists error (RMS$_REX) is 
returned as the completion status (RAB$L_STS). If you specify the update-if 
(RAB$V_UIF) record option, VMS RMS overwrites the existing record instead 
of returning an error message. If you try to use the update-if option but do 
not have update access, VMS RMS rejects the operation and issues a file 
access error (RMS$_FAC). 
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Inserting Records into Indexed Files 


In an indexed file, you can use sequential access or random access by key 
mode. When sequential access is used to insert records, the primary key 
value of the record to be inserted must be consistent with the specified sort 
order of the file. That is, the key must be greater than or equal to the primary 
value of the previous record if ascending sort order is specified. If descending 
sort order is specified, the key must be less than or equal to the primary key 
value of the previous record. 


The records cannot be larger than the size established when the file was 
created if a maximum length was specified. Each record written must contain 
a primary key, but the records do not have to contain alternate keys. If 
alternate keys are partially or completely missing because of the record length 
limitation, VMS RMS does not make an entry for the record in the associated 
alternate index. Put services to an indexed file do not require a separate key 
value or key of reference. By examining the contents of the primary key in 
the record, VMS RMS determines where to insert the record. 


When inserting a record into an indexed file, VMS RMS compares the key 
values in the record with the key values of records previously inserted into 
the file to determine whether or not the new record’s key value duplicates 
any existing key values. If the record duplicates a key value in an index 
where duplication is not allowed, VMS RMS rejects the operation with an 
RMS$_DUP error code. Where duplicate keys are allowed, VMS RMS inserts 
the record. 


Records with duplicate keys are inserted in chronological order; that is, VAX 
RMS inserts each record having duplicate keys at the end of a “chain” of 
identically keyed records so that newer records are stored closer to the end of 
the file regardless of sort order. 


If you specify the update-if (RAB$V_UIF) option when duplicates are not 
allowed on the primary key, VMS RMS overwrites the existing record 

with the same primary key value, rather than returning a duplicate record 
error (RMS$_DUP). This gives the appearance of an Update service being 
performed on the existing record. Alternate key values are modified to reflect 
the newly inserted record. 


To use the RAB$V_UIF option, you must have update access to the file. If 
update access to the file is not permitted, the Put service (which becomes an 
Update service when this option is selected) fails, and VMS RMS returns a 
file access error (RMS$_FAC). 


Be careful when invoking the PUT service with the RAB$V_UIF option and 
automatic record locking for a shared file. The Put service, unlike the Update 
service, momentarily releases record locks previously applied by a Get or 
Find service, until the PUT service is converted into an Update service. This 
could allow another record stream to delete or update the record between the 
invocation of the Put service and the conversion to an Update service. To 
avoid this complication, you should use the Update service instead of the Put 
service with the update-if option to update an existing record in a file-sharing 
situation. 


The record address field (RAB$L—RBF) and the record size field (RAB$W_ 
RSZ) are required inputs to the Put service, and some Put service options 
require additional fields. 


A successful Put service returns the record file address (RFA) in the RAB$W_ 
RFA field. 
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Table RMS-35 lists the control block fields read as input by the Put service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-—35 Put Service RAB Input Fields 


Field Name 


RABSW_ISI 
RAB$L_KBF 


RAB$B_KSZ 


RAB$SB_RAC 
RAB$L_RBF 
RABSL_RHB 


RAB$W_RSZ 
RAB$L_ROP 


Option or 
XAB Type 


RAB$SV_ASY 


RAB$V_CCO? 


RAB$V_LOA 


RAB$V_REA? 


RABSV_RLK? 


RAB$SV_TMO? 


RABSV_TPT 


RABS$V_UIF 


Description 


Internal stream identifier (required). 


Key buffer address (used as input only with 
random access by relative record number 
mode). 


Key size (used only if RAB$B_RAC is KEY 
and the file is a relative file). 


Record access mode (SEQ, KEY)!. 
Record buffer address. 


Record header buffer (applies only to 
variable with fixed control records). 


Record size. 
Record-processing options. 


Asynchronous: performs Put services 
asynchronously. 


Cancel CTRL/O: guarantees that terminal 
output is not discarded if the operator 
enters CTRL/O. 


Load: specifies that buckets are to be 
loaded according to the fill size established 
at file creation time. 


Lock for read: allows other users read 
access to the record. This is not valid for 
relative files. 


Read of locked record allowed: specifies 
that a user who locks a record for 
modification is allowing the locked record 
to be read by other accessors. 


Timeout: indicates that the content of the 
timeout period field (RAB$B_TMO) is to be 
used. 


Truncate-on-put: specifies that a Put 
service with a record accessed sequentially 
can occur at any point in the file, truncating 
the file at that point. 


Update-if: converts a Put service to a 
record that already exists to an Update 
service. 


'The default for the RAB$B_RAC field is RAB$C_SEQ. 


2This field is not supported for DECnet operations. 


3This option is meaningless unless you specify manual unlocking. 
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Table RMS-—35 (Cont.) Put Service RAB Input Fields 
Option or 
Field Name XAB Type Description 
RAB$V_ULK Manual unlocking: specifies that records 
cannot be automatically unlocked. 
RAB$V_WBH Write behind: two buffers are allocated to 
allow multibuffering. 
RAB$SV_WAT Wait: if record is locked, wait until it is 
available (applies to relative files). 
RAB$B_TMO' Timeout period: a value of zero indicates 
that VMS RMS should not wait to complete 
a Put service (applies to mailbox devices 
only). 
'The default for the RAB$B_RAC field is RAB$C_SEQ. 
Table RMS-36 lists the control block fields written as output by the Put 
service. 
Table RMS—36 Put Service RAB Output Fields 
Option or 
Field Name XAB Type Description 
RAB$L_BKT Bucket code: set to the relative record number 
for sequential access to relative files. 
RABSW_RFA Record file address. 
RAB$L_STS Completion status code (also returned in 
register 0). 
RAB$L_STV Status value’. 
1On the successful completion of a Put service to a record-oriented device, the RAB$L _ 
STV field contains the second longword of the I/O status block. See the VMS I/O User's 
Reference Manual: Part | in the VMS I/O User's Reference Volume for details on specific 
devices. 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG 
RMS$_BUG_DAP RMS$_CDA RMS$_CHK 
RMS$_CONTROLC RMS$_CONTROLO RMS$_CONTROLY 
RMS$_DME RMS$_DNR RMS$_DUP 
RMS$_ENQ RMS$_EXT RMS$_FAC 
RMS$_FTM RMS$_FUL RMS$_ IBF 
RMS$_IDX RMS$_IOP RMS$_IRC 
RMS$_ IS! RMS$_KBF RMS$_KEY 
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RMS$_KSZ RMS$_MRN RMS$_NEF 
RMS$_NET RMS$_NETFAIL RMS$_NORMAL 
RMS$_OK_ALK RMS$_OK_DUP RMS$_OK_IDX 
RMS$_PENDING RMS$_PLG RMS$_RAB 
RMS$_RAC RMS$_RBF RMS$_RER 
RMS$_REX RMS$_RHB RMS$_RLK 
RMS$_RPL RMS$_RRV RMS$_RSA 
RMS$_RSZ RMS$_RVU RMS$_SEQ 
RMS$_SOO RMS$_STR RMS$_SUC 
RMS$_SUP RMS$_SUPPORT RMS$_SYS 
RMS$_TRE RMS$_WBE RMS$_WER 
RMS$_WLK RMS$_WPL 
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The Read service retrieves a specified number of bytes from a file 
(beginning on a block boundary) and transfers them to memory. A Read 
service using block I/O can be performed on any file organization. 











FORMAT SYS$READ rab [,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Read service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 


DESCRIPTION 
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To use the Read service, you must do the following: 


1 Supply a buffer area into which VMS RMS is to transfer data (user record 
area address field, RAB$L_UBF). 


2 Indicate the number of bytes to be transferred (user record area size field, 
RAB$W_USZ). 


3 Indicate the first virtual block number (VBN) for the transfer (bucket 
number field, RAB$L_—BKT). If the value for the VBN is 0, the transfer 
starts with the block indicated by the NBP (Next Block Pointer). 


Table RMS-37 lists the control block fields read as input by the Read service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS-37 Read Service RAB Input Fields 


Field Name 


RABSL_BKT 


RAB$SW_ISI 
RABS$L_ROP 


RABS$L __UBF 


RABSW_USZ 


Description 


Bucket number: must contain the virtual block number of the 
first block to read. When this field has a value of O, then the 
next block is read. 


Internal stream identifier. 


Record-processing option, ASY (RAB$V_ASY). Asynchronous: 
performs Read services asynchronously. 


User record buffer address. For block I/O, alignment of the 
user's record buffer on a page or at least a quadword boundary 
may improve performance. 


User record area size: indicates the length of the transfer, in 
bytes’. 


1Certain devices require that an even number of bytes be transferred. For further details, 
see the VMS I/O User’s Reference Manual: Part | in the VMS I/O User’s Reference 


Volume. 


Table RMS-38 lists the control block fields written as output by the Read 


service. 


Table RMS—38 Read Service RAB Output Fields 


Field Name 


RAB$L__RBF 
RABSW_RFA 
RABSW-_RSZ 
RABS$L_STS 
RABS$L_STV 


Description 


Record address. 

Record file address. 

Record size: indicates the actual number of bytes transferred. 
Completion status code (also returned in register O). | 
Status value. 


RMS-—77 


VMS RMS Services 





$READ 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG_DAP RMS$_CDA 
RMS$_CONTROLC RMS$_CONTROLY RMS$_DME RMS$_DNR 
RMS$_EOF RMS$_FAC RMS$_FTM RMS$_IOP 
RMS$_ISI RMS$_NET RMS$_NETFAIL § RMS$_ 

NORMAL 

RMS$_PBF RMS$_ PENDING RMS$_RAB RMS$_RER 
RMS$_RSA RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_TMO RMS$_UBF 
RMS$_USZ RMS$_WBE 
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The Release service unlocks the record specified by the contents of the 
record file address (RAB$W_RFA) field of the RAB. 








FORMAT SYS$RELEASE rab/,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 





ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Release service call. The rab argument is the address of the RAB control 


block. 

err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


suc 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The Release service unlocks a specified record (see also the discussion of the 
Free service). If the named record is not locked, VMS RMS returns a status 


code of RMS$_RNL. 


Table RMS-39 lists the control block fields read as input and written as 
output by the Release service. For additional information on the fields 


accessed by this service, see Part II. 


Table RMS-—39 Release Service RAB Input and Output Fields 


Field Name Description 
Input RABSW_ISI Internal stream identifier (required). 
RABSW_RFA Record file address (required). 
Output RAB$L_STS Completion status code (also returned in register Q). 


RABSL_STV Status value. 





RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_BLN RMS$_BUG_DAP RMS$_CDA 
RMS$_ISI RMS$_NET RMS$_NETFAIL RMS$_NORMAL 
RMS$_PENDING RMS$_RAB RMS$_RNL RMS$_RSA 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 
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$REMOVE 


The Remove service deletes a file name from a directory. It is the reverse 
of the Enter service. 








FORMAT SYS$REMOVE | fab/,/err] [, suc] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 





ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for 
the Remove service call. The fab argument is the address of the FAB control 


block. 

err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_.procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. . 


RMS-81 


VMS RMS Services 


$REMOVE 





DESCRIPTION 
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The Remove service searches for the first file name that matches the expanded 
name string and directory ID in the user’s NAM block, and then it deletes 
the file name without deleting the actual file. The Remove service is similar 
to the Erase service, except that the Erase service also deletes the file after 
performing an implicit Remove. Note that you must close the file before 
invoking the Remove service (that is, the value of FAB$W_IFI must be 0). 


The Remove service accepts wildcard characters and search lists, and it 

is usually preceded by a call to the Parse service in order to fill in the 
appropriate fields of the NAM block. Because the Remove service returns 
the wildcard context field of the NAM block (NAM$L_WCC), the Remove 
service can be used on multiple successive calls in order to remove successive 
file names that match a wildcard file specification. 


Be careful when you mix calls to the Search and Remove services. For 
example, assume you invoke the following service sequence: 


e PARSE 


e SEARCH 
e REMOVE 
e SEARCH 
e REMOVE 


VMS RMS responds by doing the following: 


1 Searches for the first file specification that matches the expanded name 
string 


2 Searches for and removes the second file specification 
3 Searches for the third file specification 


4 Searches for and removes the fourth file specification 


If you want to remove the directory entry of a file and you have that file’s 
ID, then you can improve the speed of the Remove service by specifying the 
NAM bit in the FAB$L_FOP field. In order to do this properly, you must first 
parse the name of the file specification (to clear the NAM$W_FID field), place 
the correct FID in the NAM block, and then perform the Remove service. 


The Remove service is not supported for DECnet operations for remote file 
access between two VMS systems. 


Table RMS-40 lists the control block fields read as input by the Remove 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS—40 Remove Service FAB and NAM Block Input Fields 


Field Name Description 


FAB$L_FOP' File-processing option, FAB$V_NAM only. NAM block inputs: 


indicates that the NAM$W_FID field is used as input. 
FABSW_IFI Internal file identifier (must be zero). 


This field is not supported for DECnet operations. 
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Table RMS—40 (Cont.) Remove Service FAB and NAM Block Input 


Field Name 


FABSL_NAM 
NAM$W_DID' 


NAM$T_DVI' 
NAM$L_ESA 
NAM$B_ESL 


NAM$W_ FID’ 


NAMS$L_FNB 
NAMS$L_RSA 


‘NAM$B_RSL 
NAM$B_RSS 
NAM$L_WCC 


Fields 
Description 


Name block address. 


Directory identification; identifies the directory from which the 
file is to be removed. 


Device identification; identifies the device containing the 
directory from which the file is to be removed. 


Expanded string area address specifying the name, type, and 
version of the file to be removed. 


Expanded string length. 


File identification: if nonzero and FAB$L__FOP field FAB$V_ 
NAM bit is set in the input FAB, the first file in the directory 
with this file identification is removed. 


File name status bits (wildcard character bits only). 


Resultant string area address: specifies the name, type, and 
version number of the last file removed (required for wildcard 
character processing). 


Resultant string length. 
Resultant string area size. 
Wildcard character context value. 


'This field is not supported for DECnet operations. 


Table RMS-41 lists the control block fields written as output by the Remove 


service. 


Table RMS—41 


Field Name 


FABSL_STS 
FAB$SL_STV 
NAM$B_RSL 
NAM$L_WCC 


Remove Service FAB and NAM Block Output Fields 


Description 


Completion status code (also returned in register 0). 
Status value. 

Resultant string length. 

Wildcard context value. 


The resultant string is moved to the buffer described by the NAM$L_RSA 
and NAM$B_RSS fields (only if both fields are nonzero on input). 
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RETURN The following condition values are described in Appendix A: 

VALUES RMS$_BLN RMS$_CDA = RMS$_CHN — RMS$_DEV 
RMS$_DME RMS$_DNF RMS$_DNR RMS$_DVI 
RMS$_ESA RMS$_ESL RMS$_FAB RMS$_FNF 
RMS$_IFI RMS$_NAM RMS$_NMF RMS$_NORMAL 
RMS$_PRV RMS$_RMV RMS$_RSL RMS$_RSS 
RMS$_RST RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_WCC RMS$_WLD 
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You can use this service to change the name, type, or version of a file, or 
to move a file to another directory by changing its directory specification. 
However, note that you cannot use this service to move a file to another 
device. 





FORMAT 


SYSS$RENAME  old-fab , [err] ,[suc] ,new-fab 





RETURNS 


VMS usage: cond_value 

type: longword (unsigned) 
access: write only 
mechanism: by value 


The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 





ARGUMENTS 


old-fab 

VMS usage: fab 

type: longword (unsigned) 
access: modify 

mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Rename service call. The old-fab argument is the address of the FAB control 
block that specifies the old file name. 


err 

VMS usage: ast—procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


suc 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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new-fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
The new-fab argument is the address of the FAB control block that specifies 
the new file name. 

Note: If you invoke the Rename service using the $RENAME macro and if 
you do not specify arguments, you must construct an additional field 
within your argument list to contain the address of the FAB that specifies 
the new file name. This additional field is placed in the argument list 
following the field for the success completion routine (see Part I), and the 
argument count is set to 4. 

DESCRIPTION The Rename service performs the equivalent of two Parse services (old and 
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new name), a Search service for the old directory, an Enter service to insert 
the new file name into the new directory, and a Remove service to delete the 
old file name from the old directory. 


Note that you must close the file before invoking the Rename service 
(FAB$W_IFI must be 0), and no wildcard character specifications are allowed. 
You can move a file from one directory to another using this service, but both 
directories must be on the same disk device. 


If the Rename service is successful, the new directory entry is created and the 
old entry is deleted. If the service fails, the old entry remains and the new 
entry is deleted. 


Table RMS-42 lists the fields in two FABs and two NAM blocks that the 
Rename service uses as input and output. In the table, these blocks are called 
FAB1 and NAM1 for the old entry, and FAB2 and NAM2 for the new entry. 
For output, FAB2 is not used, although it must be in writable memory. To 
check or signal the completion codes in FAB$L_STS and FAB$L_STV, use 
the first FAB (FAB1). 


The resultant file specification string for each of the names (old and new) is 
placed in the buffer described by the NAM$L_RSA and NAM$B_RSS fields 
of the separate NAM blocks (only if both fields are nonzero). 


Table RMS-—42 lists the control block fields read as input by the Rename 
service. For additional information on the fields accessed by this service, see 
Part II. 
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Table RMS—42 Rename Service FAB and NAM Block Input Fields 





Control Block Field Name 


FAB1 and FAB2 FAB$L_DNA 
FAB$B_DNS 
FAB$L_FNA 
FAB$B_FNS 
FABSW_IFI 
FABSL_NAM 


NAM1 and NAM2 NAMS$L_ESA 


NAM$B_ESS 


NAMS$L —RLF 
NAMS$L_—RSA 
NAM$B_RSS 


Related file NAM NAM$L_RSA 


blocks 
NAM$B_RSL 
NAMS$L—FNB 


Description 


Default file specification string address. 
Default file specification string size. 
File specification string address. 

File specification string size. 

Internal file identifier (must be zero). 
Name block address. 


Expanded string area address 
(must be nonzero). 


Expanded string area size 
(must be nonzero). 


Related file NAM block address. 
Resultant string area address. 

Resultant string area size. 

Related file resultant string area address. 


Related file resultant string length. 
Related file name status bits. 


Table RMS-43 lists the control block fields written as output by the Rename 


service. 


Table RMS-—43 Rename Service FAB and NAM Block Output Fields 


Control Block Field Name 


FAB1 FAB$L_STS 


FAB$L_STV 
NAM$W_DID' 
NAM$T_DVI' 
NAM$B_ESL 
NAM$W_-FID' 
NAMS$L_FNB 
NAM$B_RSL 
NAM$L_WCC 


NAM1 and NAM2 


Description 
Completion status code (also 
returned in register 0). 
Status value. 

Directory identification. 
Device identification. 
Expanded string length. 
File identification. 

File name status bits. 
Resultant string length. 
Wildcard context. 


'This field is not supported for DECnet operations. 
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RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACC RMS$_BLN RMS$_BUG_DDI 
RMS$_CDA RMS$_CHN RMS$_DEV 
RMS$_DIR RMS$_DME RMS$_DNA 

‘ RMS$_DNF RMS$_DNR RMS$_DVI 

RMS$_ENT RMS$_ESA RMS$_ESS 
RMS$_FAB RMS$FNA RMS$_FNM 
RMS$_IDR RMS$_IFI RMS$_LNE 
RMS$_NAM RMS$_NET RMS$_NETFAIL 
RMS$_NMF RMS$_NORMAL RMS$_PRV 
RMS$_QUO RMS$_REENT RMS$_RLF 
RMS$_RMV RMS$_RSS RMS$_RST 
RMS$_RUNDOWN RMS$_STR RMS$_SUC 
RMS$_SUPPORT RMS$_SYN RMS$_SYS 
RMS$_TYP RMS$_VER RMS$_WLD 
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The Rewind service sets the context of a record stream to the first record 
in the file. VMS RMS alters the context of the next record to indicate the 
first record as being the next record. 








FORMAT SYSS$REWIND rab/,[err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 





ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Rewind service call. The rab argument is the address of the RAB control 


block. 

err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


- mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


The Rewind service implicitly performs the Flush and Free services, writing 
out all I/O buffers and releasing all locked records. This service is valid for 
all file organizations on disk volumes and for sequential files on tape volumes. 
For indexed files, the key of reference field establishes the index to be used 
for subsequent sequential accesses. You cannot rewind a unit record device, 
such as a card reader, a mailbox, a printer, or a terminal. You cannot rewind 
indirectly accessed process-permanent files. Also, you cannot rewind a file 
that was opened with the FAB$L_FOP field FAB$V_SQO option set. 


Table RMS-—44 lists the control block fields read as input by the Rewind 
service. For additional information on the fields accessed by this service, see 
Part II. 

Table RMS—44 Rewind Service RAB Input Fields 

Field Name Description 

RABSW_ISI Internal stream identifier (required). 

RAB$B_KRF Key of reference (used only with indexed files). 


RAB$L ROP Record-processing option, RAB$V_ASY option only. 
Asynchronous: performs a Rewind service asynchronously. 


Table RMS-45 lists the control block fields written as output by the Rewind 
service. 


Table RMS-—45 Rewind Service RAB Output Fields 
Field Name Description 


RAB$L_STS Completion status code (also returned in register O). 
RAB$L_STV Status value. 





RETURN 
VALUES 
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The following condition values are described in Appendix A: 


RMS$_ACT RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BOF RMS$_BUG_DAP RMS$_CDA RMS$_DME 
RMS$_DNR RMS$_DPE RMS$_IOP RMS$_ISI 
RMS$_KRF RMS$_NET RMS$_NETFAIL RMS$_NORMAL 
RMS$_PENDING RMS$_QUO RMS$_RAB RMS$_RSA 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 
RMS$_SYS RMS$_WBE RMS$_WER RMS$_WLK 


$SEARCH 
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The Search service scans a directory file and fills in various NAM block 
fields. This service should be preceded by the Parse service, in order to 
initialize the NAM block appropriately. 











FORMAT SYS$SEARCH fab/,/err] [, suc] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset FAB$L_STS. 
Symbolic offset FAB$L_STV may contain additional status information. 
ARGUMENTS fab 
VMS usage: fab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


FAB control block whose contents are to be used as indirect arguments for the 
Search service call. The fab argument is the address of the FAB control block. 


err 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION The basic functions of the Search service and the Parse service are performed 
automatically as part of the Open, Create, and Erase services. Note that you 
must close the file before invoking the Search service (FAB$W_IFI must be 0). 


When called, the Search service scans the directory file specified by the 
directory identification (NAM$W_DID) field of the NAM block. It looks for 
an entry that matches the file name, type, and version number specified by 
the expanded string area address and expanded string length fields. Upon 
finding a match, VMS RMS returns the file name, type, and version number 
in the buffer described by the resultant string area address and size fields. 
VMS RMS also fills in the file identification field to enable a subsequent 
open-by-NAM-block operation. You can also use the Search service to obtain 
a series of file specifications whose names match a file specification that 
contains wildcard characters or search lists. 


The resultant file specification string is placed in the buffer described by 

the resultant string area address (NAM$L_RSA) and size (NAM$B_RSS) 
fields of the NAM block (only if both fields are nonzero). The NAM$L_RSA 
and NAM$B_RSS fields must be specified (nonzero) for wildcard character 
processing. 


Table RMS-46 lists the control block fields read as input by the Search 
service. For additional information on the fields accessed by this service, see 
Part II. 


Table RMS—46 Search Service FAB and NAM Block Input Fields 


Field Name . Option Description 

FABSW_IFI Internal file identifier (must be zero). 

FAB$L_NAM Name block address. 

NAM$W_DID' Directory identification of the 
directory to be searched. 

NAM$T_DVI' Device identification of device 
containing directory to be searched. 

NAM$L_ESA Expanded string area address: 
specifies file name, type, and version 
of file. 

NAM$B_ESL Expanded string length. 

NAMS$L_FNB File name status bits (wildcard 
character options only). 

NAM$B_NOP NAM block options. 

NAM$V_PWD Password: indicates that a password 


contained in a DECnet access 
control string, if present in a file 
specification, is to be left unaltered 
in the expanded and resultant strings 
(instead of being replaced by the 
word “password"). 


'This field is not supported for DECnet operations. 
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Table RMS—46 (Cont.) Search Service FAB and NAM Block Input 


Field Name 


NAM$L_RSA 


NAM$B_RSS 


NAMS$L_—WCC 


NAM$V_SRCHXABS 


Fields 


Option Description 
NAM$V_NOCONCEAL Do not conceal device name: 


indicates that when a concealed 
device logical name is present, the 
concealed device logical name is to 
be replaced by the actual physical 
device name in the resultant string. 


Performs Display service on 
remote files (for output fields, see 
description of Display service). 


Resultant NAM block string area 
address: specifies name, type, and 
version of last file found (required for 
wildcard character processing). 


Resultant NAM block string area 
size. 


Wildcard character context value. 


Table RMS-47 lists the control block fields written as output by the Search 


service. 


Table RMS—47_ Search Service FAB and NAM Block Output Fields 


Field Name 


FAB$L_STS 
FABSL_STV 
NAM$B_DEV 
NAMS$L_DEV 
NAM$B_DIR 
NAMS$L __DIR 
NAM$W_FID' 
NAMS$L _FNB 


NAM$B_NAME 


NAM$L_NAME 
NAMS$B_NODE 
NAM$L_—NODE 
NAM$B_RSL 
NAM$B_TYPE 
NAMS$L_TYPE 


NAM$B_VERSION 


Description 


Completion status code (also returned in register 0). 
Status value. 

Address of file specification device descriptor. 
Size of file specification device descriptor. 
Address of file specification directory descriptor. 
Size of file specification directory descriptor. 

File identification. 

File name status bits (wildcard status bits only). 
Address of file specification name descriptor. 
Size of file specification name descriptor. 
Address of file specification node descriptor. 
Size of file specification node descriptor. 
Resultant string length. 

Address of file specification type descriptor. 
Size of file specification type descriptor. 


Address of file specification version descriptor. 


'This field is not supported for DECnet operations. 
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$SEARCH 

Table RMS—47 (Cont.) Search Service FAB and NAM Block Output 
Fields 

Field Name Description 
NAMS$L_VERSION Size of file specification version descriptor. 
NAM$L_—WCC Wildcard character context value. 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACS RMS$_BLN RMS$_CHN RMS$_DEV 
RMS$_DME RMS$_DNF RMS$_DNR RMS$_DVI 
RMS$_ESA RMS$_ESL RMS$_FAB RMS$_FND 
RMS$_FNF RMS$_IFI RMS$_NAM RMS$_NET 
RMS$_NETFAIL RMS$_NMF RMS$_NORMAL RMS$_NOVALPRS 
RMS$_PRV RMS$_RSL RMS$_RSS RMS$_RST 
RMS$_STR RMS$_SUC RMS$_SUP RMS$_SUPPORT 


RMS$_SYS RMS$_.WCC 
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The Space service lets you space (skip) a tape file forward or backward a 
specified number of blocks. 











FORMAT SYS$SPACE rab [err] [, suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Space service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast—_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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$SPACE 
DESCRIPTION The Space service is intended primarily for use with magnetic tape files; the 
tape is skipped forward or backward the number of blocks specified in the 
bucket number field. (The size of each block on any tape is specific to that 
tape and is defined on the tape itself, not by VMS or VMS RMS.) If the value 
in this field is positive, the tape skips forward; if the value is negative, the 
tape skips backward. For disk files, the next block pointer (NBP) is updated 
to reflect the new sequential operation position. 
Table RMS-48 lists the control block fields read as input by the Space service. 
For additional information on the fields accessed by this service, see Part II. 
Table RMS-—48 Space Service RAB Input Fields 
Field Name Description 
RABS$L_BKT Bucket code: indicates the number of blocks to space forward 
(positive value) or backward (negative value). 
RABS$W_ISI Internal stream identifier. 
RAB$L_ROP Record-processing option, RAB$V_ASY only. Asynchronous: 
performs Space services asynchronously. 
Table RMS-49 lists the control block fields written as output by the Space 
service. 
Table RMS-49 Space Service RAB Output Fields 
Field Name Description 
RAB$L_STS Completion status code (also returned in register 0). 
RAB$L_STV Status value (the absolute number of blocks actually skipped; 
the value is always positive). 
RETURN The following condition values are described in Appendix A: 
VALUES RMS$_ACT RMS$_BLN RMS$_BOF RMS$_BUG_DAP 
RMS$_CDA RMS$_DME RMS$_DNR RMS$_DPE 
RMS$_EOF RMS$_IOP RMS$_ISI RMS$_NET 
RMS$_NETFAIL RMS$_NORMAL RMS$_PENDING RMS$_RAB 
RMS$_RSA RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_WBE 
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S$TRUNCATE 


The Truncate service removes records from the end of a sequential file. 














FORMAT SYSSTRUNCATE  rab/,/err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
RAB control block whose contents are to be used as indirect arguments for 
the Truncate service call. The rab argument is the address of the RAB control 
block. 
err 
VMS usage: ast—procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 
suc 
VMS usage: ast—procedure 
type: procedure entry mask 
access: call without stack unwinding 
mechanism: by reference 
AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
DESCRIPTION You can only truncate a sequential file that is open for exclusive access. The 


file-sharing (FAB$B_SHR) field must be set or defaulted to NIL, and the file 
access (FAB$B_FAC) field must specify a truncate access (FAB$V_TRN). 
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S$TRUNCATE 
The Truncate service deletes the record indicated as the current record, and all 
following records. You can only use this service immediately after successful 
execution of a Get or Find service (thereby setting the context of the current 
record). 

VMS RMS declares the logical end of file to be the starting record position 

for the truncation and then uses the end of file to establish the context of the 

next record. You can then add records to the file by issuing successive Put 

services. 

Table RMS-50 lists the control block fields read as input by the Truncate 

service. For additional information on the fields accessed by this service, see 

Part II. 

Table RMS-—50 _ Truncate Service RAB Input Fields 

Field Name Description 

RAB$W_ISI Internal stream identifier (required). 

RAB$L__ROP Record-processing option, RAB$V_ASY only. Asynchronous: 
performs Truncate services asynchronously. 

Table RMS-51 lists the control block fields written as output by the Truncate 

service. 

Table RMS—51_ Truncate Service RAB Output Fields 

Field Name Description 

RAB$L_STS Completion status code (also returned in register 0). 

RAB$L_STV Status value. 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_ATR RMS$_ATW = RMS$_BLN 
RMS$_BUG_DAP RMS$_CDA RMS$_CUR RMS$_DEADLOCK 
RMS$_DME RMS$_DNR RMS$_DPE RMS$_FAC 
RMS$_IOP RMS$_1SI RMS$_NET RMS$_NETFAIL 
RMS$_NORMAL RMS$_PENDING RMS$_RAB RMS$_RER 
RMS$_RSA RMS$_STR RMS$_SUC RMS$_SUP 
RMS$_SUPPORT RMS$_SYS RMS$_WBE RMS$_WER 
RMS$_WLK 


RMS-—98 


VMS RMS Services 
$S$UPDATE 


SUPDATE 


The Update service allows you to modify the contents of an existing 
record in a file residing on a disk device. 








FORMAT SYS$UPDATE rab [err] [,suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 


mechanism: by value 


The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 





ARGUMENTS rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Update service call. The rab argument is the address of the RAB control 


block. 

err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 
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The record to be updated by the Update service must first be locked by this 
stream, using either a Find or Get service. When updating a record, you must 
use move mode (not locate mode); that is, you must supply a buffer. 


The record length for sequential files cannot change. For relative files with 
variable-length or variable with fixed-length control records, the length of the 
replacement record can be different from the length of the original record, but 
cannot be larger than the maximum size you set when you created the file. 


For stream format files, the Update service functions in the same manner as 
the Put service, with one exception. When using the Update service, you do 
not have to set the RAB$L_ROP field RAB$V_TPT option to update data in 
the middle of a file. 


For indexed files, the length of the replacement record written by the Update 
service may be different from the original record but RMS does not permit 
you to change the primary key. Each replacement record must be large 
enough to contain a complete primary key, but it does not have to contain all 
alternate keys. 


If an alternate key is partially or completely missing in the replacement 
record, the key must have the characteristic that the values can change; this is 
also true if the replacement record contains a key that was not present in the 
original record. 


Update operations to an indexed file do not require a key value or key of 
reference. Before writing the record, VMS RMS compares the key values 
(primary and alternate) in the replacement record with the key values of the 
original record already existing in the file. This comparison takes the defined 
characteristics of each key into account. For example, if a particular key is not 
allowed to change, VMS RMS rejects the operation with an RMS$_CHG error 
code if the replacement record contains an altered value in the associated key. 
Similarly, this comparison determines whether the replacement record would 
result in the presence of duplicate key values among records of the file. If 
duplicates would occur, VMS RMS verifies the defined characteristics for the 
keys being duplicated. If duplicates are not allowed for a particular key, VMS 
RMS rejects the operation with an RMS$_DUP error code. If duplicates are 
allowed, VMS RMS performs the operation. 


Subsequent sequential operations on a given index retrieve records with 
identical key values in the order in which the records were written. 


Table RMS-52 lists the control block fields read as input by the Update 
service. For additional information on the fields accessed by this service, see 
Part Il. 


Table RMS-—52 Update Service RAB Input Fields 


Field Name Option Description 

RAB$SW_ISI Internal stream identifier (required). 
RAB$L_RBF Record buffer address. 

RAB$L_—_RHB Record header buffer (applies only to variable 


with fixed control records). 
RAB$L_ROP Record-processing options. 


Table RMS—52 (Cont.) 


Field Name 


RABSW_RSZ 


Option 
RAB$V_ASY 


RABSV_WBH 
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Update Service RAB Input Fields 


Description 


Asynchronous: performs Update services 
asynchronously. 


Write-locked: two buffers are allocated to 
allow multibuffering. 


Record size (required). 


Table RMS-53 lists the control block fields written as output by the Update 


service. 


Table RMS—53 Update Service RAB Output Fields 


Field Name 


RABSW_RFA 


RAB$L_STS 
RABS$SL_STV 


Option 


Record file address. 


Completion status code (also returned in register O). 


Status value. 





RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_ACT 
RMS$_BUG 
RMS$_CHK 
RMS$_DUP 
RMS$_FTM 
RMS$_IRC 


RMS$_NORMAL 


RMS$_PLG 
RMS$_RHB 
RMS$_RSA 
RMS$_SUC 
RMS$_TRE 
RMS$_WPL 


RMS$_ATR RMS$_ATW RMS$_BLN 
RMS$_BUG_DAP RMS$_CDA RMS$_CHG 
RMS$_CUR RMS$_DME RMS$_DNR 
RMS$_ENO RMS$_EXP RMS$_FAC 
RMS$_IBF RMS$_IDX RMS$_IOP 
RMS$_ISI RMS$_NET RMS$_NETFAIL 
RMS$_OK_DUP | RMS$_OK_IDX RMS$_PENDING 
RMS$_RAB RMS$_RBF RMS$_RER 
RMS$_RNL RMS$_RPL RMS$_RRV 
RMS$_RSZ RMS$_RVU RMS$_STR 
RMS$_SUP RMS$_SUPPORT | RMS$_SYS 
RMS$_WBE RMS$_WER RMS$_WLK 
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SWAIT 


The Wait service suspends image execution until an asynchronous record 
service completes. Upon completion of the service, VMS RMS returns 
control to your program at the point following the Wait service call. 














FORMAT SYSS$WAIT rab 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
mechanism: by reference 
RAB control block whose contents are to be used as indirect arguments for 
the Wait service call. The rab argument is the address of the RAB control 
block. It can be either the RAB whose I/O request is in progress or some 
other RAB. 
DESCRIPTION The Wait service takes no arguments to define entry points for user-written 
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completion routines; the completion routines are specified by the service 
being awaited. 


Any completion routines specified on the operation being awaited are 
declared as ASTs before VMS RMS returns control. They are executed 
before the WAIT service completes unless ASTs are disabled. Completion 
routines are always executed as asynchronous system traps (ASTs). 


Table RMS-54 lists the control block fields read as input and written as 
output by the Wait service. For additional information on the fields accessed 
by this service, see Part II. 


Table RMS—54_ Wait Service RAB Input and Output Fields 


Field 
Use Name Description 
Input RAB$W_ISI Internal stream identifier (required). 
RAB$L_STS Status completion code. 
Output RAB$L_STS Completion status code (also returned in register Q). 


VMS RMS Services 
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RETURN 
VALUES 


The following condition values are described in Appendix A: 


RMS$_BLN RMS$_CDA RMS$_1ISI RMS$_NORMAL 
RMS$_RAB RMS$_STR RMS$_SUC 


The VMS RMS completion status codes for the Wait service are determined by 
the VMS RMS service being awaited, unless the address of the RAB specified 
for the wait is different from that specified for the awaited operation. In this 
case, RMS$_NORMAL is returned. 
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SWRITE 


The Write service transfers a user-specified number of bytes (beginning 
on a block boundary) to a VMS RMS file of any file organization. 











FORMAT SYS$WRITE rab [,[err] [| suc]] 
RETURNS VMS usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
The value returned in RO is also returned in symbolic offset RAB$L_STS. 
Symbolic offset RAB$L_STV may contain additional status information. 
ARGUMENTS ~ rab 
VMS usage: rab 
type: longword (unsigned) 
access: modify 
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mechanism: by reference 


RAB control block whose contents are to be used as indirect arguments for 
the Write service call. The rab argument is the address of the RAB control 
block. 


err 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level error completion routine that the service invokes if the operation 
is unsuccessful. The err argument is the address of the entry mask of this 
user-written completion routine. 


SUC 

VMS usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST-level success completion routine that the service invokes if the operation 
is successful. The suc argument is the address of the entry mask of this 
user-written completion routine. 
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DESCRIPTION 


You specify the number of bytes to be written by the Write service in the 
record size (RAB$W_RSZ) field of the RAB and the address of the buffer for 
the transfer in the record address (RAB$L_RBF) field. In the bucket number 
(RAB$L__BKT) field, you indicate the virtual block number of the first block 
to be written; if this number is 0, the transfer starts with the block indicated 
by the NBP. 


A sequential file is automatically extended if you write a block past the end 
of the currently allocated space when using block I/O (or record I/O). For 
sequential files, VMS RMS maintains a logical end of file to correspond to the 
last block and highest byte written within the block. For relative and indexed 
files, you must use the Extend service when using block I/O. 


Table RMS-55 lists the control block fields read as input by the Write service. 
For additional information on the fields accessed by this service, see Part II. 


Table RMS—55 Write Service RAB Input Fields 


Field Name Option Description 

RAB$L_BKT Bucket number: must contain the virtual block 
number of the first block to be written. 

RAB$W_ISI Internal stream identifier. 

RAB$L_RBF Record buffer address. For block I/O, 


alignment of the user’s record buffer on a 
page or at least a quadword boundary may 
improve performance. 


RAB$L_ROP Record-processing options. 


RAB$V_ASY — Asynchronous: performs Write services 
asynchronously. 


RAB$V_TPT Truncate on Put: specifies that a Write service 
truncate the file after the transferred data. 


RABSW_RSZ Record size: indicates the transfer length, in 
bytes.' 


'Certain devices require that an even number of bytes be transferred. For further details, 
see the VMS I/O User's Reference Volume. 


Table RMS-56 lists the control block fields written as output by the Write 
service. 

Table RMS-—56 Write Service RAB Output Fields 

Field Name Description 

RABSW_RFA Record file address. 


RAB$L_STS Completion status code (also returned in register 0). 


RAB$L_STV Status value: contains the actual number of bytes transferred if 
an end-of-file error occurs. 
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SWRITE 

RETURN The following condition values are described in Appendix A: 

VALUES RMS$_ACT RMS$_ATR RMS$_ATW 
RMS$_BLN RMS$_BUG_DAP RMS$_CDA 
RMS$_CONTROLC RMS$_CONTROLO RMS$_CONTROLY 
RMS$_DME RMS$_DNR RMS$_EOF 
RMS$_EXT RMS$_FAC RMS$_FTM 
RMS$_FUL RMS$_IOP RMS$_1SI 
RMS$_NET RMS$_NETFAIL RMS$_NORMAL 
RMS$_PENDING RMS$_RAB RMS$_RBF 
RMS$_RSA RMS$_RSZ RMS$_STR 
RMS$_SUC RMS$_SUP RMS$_SUPPORT 
RMS$_WBE RMS$_WER RMS$_WLK 
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This appendix includes two tables: one is a listing of VMS RMS completion 
status codes ordered by the hexadecimal coding, and the other is a more 
descriptive listing ordered alphabetically. See Part III for a listing of the status 
codes applicable to individual VMS RMS services. 


This appendix lists completion status codes for the RMS Journaling product 
and some of the completion status codes for the SNA VMS Data Transfer 
Facility but does not provide details. See the VAX RMS Journaling Manual 
for an explanation of RMS Journaling status codes and the DECnet/SNA VMS 
Data Transfer Facility User’s Guide for details of the SNA VMS Data Transfer 
Facility completion status codes. VMS RMS completion status error codes 
generally fall into one of four groups: 


e Programming errors 
e Program design errors 
e System environment errors 


e Operator/user errors 
Here is a brief description of each group: 


Error Group 


Programming Errors 

These errors are caused by incorrect programming and are usually detected 
during the early stages of developing and debugging a program that uses 
VMS RMS. Typical examples are missing values for required fields, referring 
to a RAB instead of a FAB, invalid address for a buffer, and so forth. This 
type of error is generally self-explanatory and usually requires only a minor 
change to the program. 


Program Design Errors 

These errors are caused by more subtle errors that may rarely occur, 
particularly if asynchronous record I/O, multistreamed sharing, or shared 
files are involved. These errors may occur long after a program has been 
in use and could require either a major program revision or the addition of 
substantial error recovery code to handle the error conditions. Record-lock 
errors, resource-exhaustion errors, and record-stream-currently-active errors 
are typical progam design errors. 


System Environment Errors 

These errors include hardware errors and VMS RMS or other system software 
errors that are not caused by your program. You may need to add substantial 
defensive error-handling code or you may be able to run the program again 
without error. 


Operator/User Errors 


These errors include errors by the user of the program, such as not mounting 
a device before running the program, or typing an invalid file specification. 
As with system environment errors, you may need to add substantial 
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defensive error-handling code or simply reprompt the user for the correct 
information or user action. 


These are conditions in which completion status codes may not be returned 
as expected: 


¢ The completion status codes that apply to the Close service do not include 
errors introduced by the FAB$V_SCF option and the FAB$V_SPL option. 
If the request is serviced successfully, then a success completion code is 
returned, even if the request is found to be in error by the job controller 
process. 


e¢ The Wait service has unique errors. This service can return any status 
code of the awaited operation. 


e Errors associated with output operations may not necessarily be reported 
as the status of a particular operation because modified I/O buffers are 
not always written out immediately. Such errors are reported as the 
status of a subsequent operation, which may be an input, output, or 
control operation. 


Procedures for signaling VMS RMS completion status codes are discussed 
in Chapter 2 for VAX languages other than VAX MACRO. VAX MACRO 
users should refer to Chapter 3 and the example programs in Chapter 4 for 
information on signaling VMS RMS errors. Note that certain errors may not 
be signaled using the FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_ 
STV fields; these are denoted below and in Chapter 2. 


A description of each completion status code is listed in this appendix. When 
an error description indicates that the STV field should be examined for a 
secondary status code, this usually indicates a non-VMS RMS completion 
status (such as an ACP completion status). Non-VMS RMS errors are not 
described in this document; see the VMS System Messages and Recovery 
Procedures Reference Volume. 


Please note that when you submit an SPR, you should also provide a 
magnetic tape copy of the file causing the error. 


When using the debugger, use the debug command EXAMINE/CONDITION 
to view the message corresponding to the value in RO or the STS field or the 
STV field. For example, you can view the error codes in the STS and STV 
fields of the FAB at symbolic address (label) MYFAB when debugging a VAX 
MACRO program by entering the following commands: 


DBG> EXAMINE/CONDITION MYFAB+FAB$L_STS 
DBG> EXAMINE/CONDITION MYFAB+FAB$L_STV 


For additional information about the debugger, see the VMS Debugger Manual. 


Table A-1 lists the codes by hexadecimal values and includes a very brief 
description of each code. Table A—2 is ordered alphabetically and provides 
more detailed descriptions of the codes. 
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Table A—1 Completion Status Hexadecimal Values and Codes 


Hex Value 


00010001 
00010001 
00010609 
00010611 
00010619 
00010631 
00010651 
00010679 
00018009 
00018011 
00018019 
0001802 1 
00018029 
00018031 
00018039 
00018041 
00018049 
00018051 
00018059 
0001806 1 
00018069 
0001807 1 
00018198 
000181A0 
000181A8 
000181B0O 
000181B8 
000181CO 
000181C8 
0001825A 
00018262 
00018272 
0001827A 
00018282 
0001828A 
00018292 
0001829A 
000182A2 


Status Code 


RMS$_SUC 
RMS$_NORMAL 
RMS$_CONTROLO 
RMS$_CONTROLY 
RMS$_CREATED 
RMS$_SUPERSEDE 
RMS$_CONTROLC 
RMS$_FILEPURGED 
RMS$_PENDING 
RMS$_OK__DUP 
RMS$_OK_IDX 
RMS$_OK_RLK 
RMS$_OK _RRL 
RMS$_KFF 
RMS$_OK_ALK 
RMS$_OK_DEL 
RMS$_OK _RNF 
RMS$_OK_LIM 
RMS$_OK__NOP 
RMS$_OK_WAT 
RMS$_CRE_STM 
RMS$_OK__RULK 
RMS$_BOF 
RMS$_RNL 
RMS$_RTB 
RMS$_TMO 
RMS$_TNS 
RMS$_BES 
RMS$_PES 
RMS$_ACT 
RMS$_DEL 
RMS$_DNR 
RMS$_EOF 
RMS$_FEX 
RMS$_FLK 
RMS$_FNF 
RMS$_PRV 
RMS$_REX 


Message Text 


Normal successful completion (same as RMS$._.NORMAL) 
Normal successful completion (same as RUS$_SUC) 
Operation completed under CTRL/O 
Operation completed under CTRL/Y 

File did not exist—was created 

Created file superseded existing version 
Operation completed under CTRL/O 

Created file deleted oldest version 
Asynchronous operation not yet completed 
Record inserted had duplicate key 

Index update error occurred 

Record locked but read anyway 

Record locked against read but read anyway 
Known file found 

Record is already locked 

Deleted record successfully accessed 
Nonexistent record successfully accessed 
Retrieved record exceeds specified key value 
XAB not filled in for block I/O 

Record locked after wait 

File created in stream format 

See the VAX RMS Journaling Manual for details. 
Beginning of file detected 

Record not locked 

nnn-byte record too large for user’s buffer 
Timeout period expired 

Terminator not seen 

Bad escape sequence 

Partial escape sequence 

File activity precludes operation 
RFA-accessed record deleted 

Device not ready, not mounted, or unavailable 
End of the file detected 

File already exists, not superseded 

File currently locked by another user 

File not found 

Insufficient privilege or file protection violation 


Record already exists 
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Table A—1 (Cont.) 


Hex Value 


000182AA 
000182B2 
000182BA 
000182C2 
000182CA 
000182D2 
000182DA 
000182E2 
000182EA 
000182F2 
0001830A 
0001831A 
00018322 
0001832A 
00018332 
0001833A 
00018342 
0001834A 
00018352 
0001835A 
000183EC 
000183F4 
000 183FC 
00018404 
0001840C 
00018414 
0001841C 
00018424 
0001842C 
00018434 
000 1843C 
00018444 
0001844C 


00018454 
000 1845C 


00018464 


Status Code 


RMS$_RLK 
RMS$_RNF 
RMS$_WLK 
RMS$_EXP 
RMS$_NMF 
RMS$_SUP 
RMS$_RSA 
RMS$_CRC 
RMS$_WCC 
RMS$_IDR 
RMS$_NOVALPRS 
RMS$_RUH 
RMS$_JND 
RMS$_BADPHASE 
RMS$_TOWDR 
RMS$_NEXDR 
RMS$_INVDRMSG 
RMS$_RU_ACTIVE 
RMS$_UNKRUFAC 
RMS$_LIMBO 
RMS$_DTFCDDREC 
RMS$_AID 
RMS$_ALN 
RMS$_ALO 
RMS$_ANI 
RMS$_AOP 
RMS$_BKS 
RMS$_BKZ 
RMS$_BLN 
RMS$_BUG 
RMS$_BUG_DDI 
RMS$_BUG_DAP 


RMS$_BUG_RU_ 
ACTIVE 


RMS$_BUG_RURECERR 


RMS$_BUG_FLUSH_ 
JNL—FAILED 


RMS$_BUG_RU_ 
ABORT_FAIL 


Completion Status Hexadecimal Values and Codes 


Message Text 


Target record currently locked by another stream 
Record not found 

Device currently write-locked 

File expiration date not yet reached 

No more files found 

Network operation not supported; DAP code = nnnn 
Record stream currently active 

Network DAP level CRC check failed 

Invalid wild card context (WCC) value 

Invalid directory rename operation 

$SEARCH operation not preceded by valid $PARSE 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
Invalid area ID = 17 

Alignment options error for area ID = n 

Invalid allocation quantity (negative, or O on $EXTEND) 
Not ANSI D format 

Allocation options error for area ID = n 

Bucket size too large (FAB) 

Inconsistent bucket size for area ID = n 

Invalid block length for control block (RAB/FAB) 
Internal RMS error condition detected 

Invalid default directory 

Data Access Protocol error detected; DAP code = nnnn 
See the VAX RMS Journaling Manual for details. 


See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 


See the VAX RMS Journaling Manual for details. 


VMS RMS Completion Status Codes 


Table A—1 (Cont.) Completion Status Hexadecimal Values and Codes 


Hex Value Status Code Message Text 

000 1848C RMS$_BUSY User structure (FAB/RAB) still in use 

00018494 RMS$_CCR Cannot connect RAB 

0001849C RMS$_CHG Invalid key change in $UPDATE (CHG not set) 
000184A4 RMS$_CHK Bucket format check failed for VBN =nnnn 

000184AC RMS$_COD Invalid or unsupported type field in XAB at nnnn 

000 184B4 RMS$_CUR No current record (operation not preceded by $GET/$FIND) 
000184BC RMS$_DAN Invalid data area number for key = n 

000184C4 RMS$_DEV Error in device name or inappropriate device type for operation 
000184CC RMS$_DIR Error in directory name 

000 184D4 RMS$_DME Dynamic memory exhausted 

000 184DC RMS$_DNA Invalid default file name string address 

000184E4 RMS$_DTP Invalid key data type for key =n 

000184EC RMS$_DUP Duplicate key detected (DUP not set) 

000 184F4 RMS$_DVI Invalid device ID value in NAM block 

000 184FC RMS$_ESA Invalid expanded string address 

00018504 RMS$_ESS Expanded string area too small 

000 1850C RMS$_FAB Invalid FAB or FAB not accessible 

00018514 RMS$_FAC Record operation not permitted by specified file access (FAC) 
0001851C RMS$_FLG Invalid key definition flags for key = n 

00018524 RMS$_FNA Invalid file name string address 

000 1852C RMS$_FNM Error in file name 

00018534 RMS$_FSZ Invalid fixed control header size 

000 1853C RMS$_FOP Invalid file options 

00018544 RMS$_FUL Device full (insufficient space for allocation) 

00018554 RMS$_IAN Invalid index area number for key = n 

0001855C RMS$_IDX Index not initialized 

00018564 RMS$_IF1 Invalid internal file identifier (IFl) value 

0001856C RMS$_IMX Invalid duplicate XAB or nondense XAB at nnnn 
00018574 RMS$_IOP Operation invalid for file organization or device 
0001857C RMS$_IRC Illegal record encountered; VBN or record number = nnnn 
00018584 RMS$_ISI Invalid internal stream identifier (ISI) value 

0001858C RMS$_KBF Invalid key buffer 

000 18594 RMS$_KEY Invalid record number key or key value 

000 1859C RMS$_KRF Invalid key-of-reference for $GET/$FIND 

000185A4 RMS$_KSZ Invalid key size for $GET/$FIND 

000185AC RMS$_LAN Invalid lowest-level-index area number for key = n 

000 185B4 RMS$_RUNDOWN Operation invalid during RMS rundown 


000 185BC 


RMS$_LNE 


Logical name translation count exceeded 


VMS RMS Completion Status Codes 


Table A—1 (Cont.) 
Status Code 
RMS$_DTFCVT 


Hex Value 


000185C4 
000185CC 


000185EC 
000185D4 
000185DC 
000185E4 
000 185F4 
000 185FC 
000 1860C 
00018614 
0001861C 
00018624 
0001862C 
00018634 
000 1863C 
00018644 
000 1864C 
00018654 
0001865C 
000 18664 
000 1866C 
00018674 
0001867C 
000 18684 
000 1868C 
00018694 
0001869C 
000186A4 
000186AC 
000186B4 
000186BC 
000186C4 
000186CC 
000 186D4 
000186DC 
000 186E4 
000186EC 


RMS$_MRN 


RMS$_DTFQUASYN 


RMS$_MRS 
RMS$_NAM 
RMS$_NEF 
RMS$_NOD 
RMS$_NPK 
RMS$_ORG 
RMS$_PBF 
RMS$_PLG 
RMS$_POS 


RMS$_DTFQUAVAL 


RMS$_QUO 
RMS$_RAB 
RMS$_RAC 
RMS$_RAT 
RMS$_RBF 
RMS$_RFA 
RMS$_RFM 
RMS$_RHB 
RMS$_RLF 
RMS$_ROP 
RMS$_RRV 
RMS$_RVU 
RMS$_RSS 
RMS$_RST 
RMS$_RSZ 
RMS$_SEQO 
RMS$_SHR 
RMS$_SIZ 
RMS$_SQO 


RMS$_DTFSESEST 


RMS$_SYN 
RMS$_TRE 
RMS$_TYP 
RMS$_UBF 


Completion Status Hexadecimal Values and Codes 


Message Text 
See the DECnet/SNA VMS Data Transfer Facility User's Guide. 


Invalid maximum record number or record number exceeds 
MRN 


See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
Invalid maximum record size 

Invalid NAM block or NAM block not accessible 

Not positioned to EOF on $PUT (sequential organization only) 
Error in node name 

No primary key defined for indexed file 

Invalid file organization value 

Invalid prompt buffer 

Error detected in file’s prolog (reconstruct file) 

Invalid key position (greater than MRS) for key = n 

See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
Error in quoted string 

Invalid RAB or RAB not accessible 

Invalid record access mode 

Invalid record attributes 

Invalid record buffer 

Invalid record file address in RAB 

Invalid record format 

Invalid record header buffer 

Invalid related NAM block 

Invalid record options 

Invalid RRV record encountered 

Error updating RRVs, some paths to data may be lost 

Invalid resultant string size 

Invalid resultant string address 

Invalid record size 

Primary key out of sequence (SEQ access) 

Invalid file-sharing (SHR) options 

Invalid key size for key = n 

Operation not sequential (SQO set) 

See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
File specification syntax error 

Error in index tree 

Error in file type 

Invalid user buffer address 


Table A—1 (Cont.) 


Hex Value 


000 186F4 
000 186FC 
00018704 
0001870C 
00018714 
0001871C 
00018724 
0001872C 
00018734 
0001873C 
00018744 
0001874C 
00018754 
0001875C 
00018764 
0001876C 
00018774 
0001877C 
00018784 
0001878C 
00018794 


000187AC 
000187B4 
000187BC 
000187C4 
000187CC 
000187D4 
000187DC 
000187E4 
000187F4 
000187FC 
00018804 
0001880C 
00018814 
0001881C 
000 18824 
00018824 


Status Code 


RMS$_USZ 
RMS$_VER 
RMS$_XNF 
RMS$_XAB 
RMS$_ESL 
RMS$_DTFSESTER 
RMS$_ENV 
RMS$_PLV 
RMS$_MBC 
RMS$_RSL 
RMS$_WLD 
RMS$_NET 
RMS$_ IBF 
RMS$_REF 
RMS$_IFL 
RMS$_DFL 
RMS$_KNM 
RMS$_IBK 
RMS$_KSI! 
RMS$_LEX 
RMS$_SEG 


RMS$_UPI 
RMS$_ACS 
RMS$_STR 
RMS$_FTM 
RMS$_GBC 
RMS$_DEADLOCK 
RMS$_EXENOLM 
RMS$_JOP 
RMS$_JNS 
RMS$_NRU 
RMS$_IFF 
RMS$_DTFTRATBL 
RMS$_DTFUNSTYP 
RMS$_DTFVERMIS 
RMS$_DTFACC 
RMS$_DTFACC 
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Completion Status Hexadecimal Values and Codes 


Message Text 


Invalid user buffer size 

Error in version number 

Required XAB not found 

Invalid XAB or XAB not accessible at nnnn 

Invalid expanded string length 

See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
Support for RMS service call or feature not present 
Unsupported prolog version 

Invalid multiblock count 

Invalid resultant string length 

Invalid wildcard operation 

Network operation failed at remote node; DAP code = nnnn 
Illegal bucket format in VBN = nnnn 

Invalid key-of-reference = n 

Index bucket fill size larger than bucket size for key =n 
Data bucket fill size larger than bucket size for key = n 

Key name buffer not accessible for key 

LAN bucket size not equal to [AN bucket size for key = n 
Index bucket cannot hold two keys for key-of-reference = n 
Invalid $EXTEND for area n containing an unused extent 


Overlapping segments or segmented key must be string for 
key=n 


UPI not set when sharing and BIO or BRO set 

Error in access control string 

User structure (FAB/RAB) became invalid during operation 
Network file transfer mode precludes operation (SQO set) 
Invalid global buffer count 

Deadlock detected 

Exceeded enqueue quota 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

Invalid file attributes for requested file access 

See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
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Table A—1 (Cont.) 


Hex Value 


00018826 
00018834 
00018836 
00018854 
00018864 
0001885C 
0001C002 
0001CO0A 
0001C012 
0001CO1A 
0001C022 
0001CO2A 
0001C032 
0001C03A 
000 1C042 
0001CO04A 
0001C052 
0001CO5A 
0001C062 
0001C072 
0001CO7A 
0001COCC 
0001CO0D4 
000 1CODC 
000 1COE4 
000 1COEC 
000 1COF4 
000 1COFC 
0001C 104 
0001C10C 
0001C114 
0001C11C 
00010124 
0001C12C 
00010134 
0001C13C 


A-8 


Status Code 


RMS$_BOGUSCOL 
RMS$_ERRREADCOL 
RMS$_ERRWRITECOL 
RMS$_DTFCRE 
RMS$_NOTSAMEJNL 
RMS$_DELJNS 
RMS$_ACC 
RMS$_CRE 
RMS$_DAC 
RMS$_ENT 
RMS$_EXT 
RMS$_FND 
RMS$_MKD 
RMS$_DPE 
RMS$_SPL 
RMS$_DNF 
RMS$_RUF 
RMS$_WRTJNL _AIJ 
RMS$_WRTJNL _BIJ 
RMS$_.WRTJNL _RUJ 
RMS$_RRF 
RMS$_ATR 
RMS$_ATW 
RMS$_CCF 
RMS$_CDA 
RMS$_CHN 
RMS$_RER 
RMS$_RMV 
RMS$_RPL 
RMS$_SYS 
RMS$_WER 
RMS$_WPL 
RMS$_IFA 
RMS$_WBE 
RMS$_ENO. 
RMS$_NETFAIL 


Completion Status Hexadecimal Values and Codes 


Message Text 


Invalid or inaccessible collating table 

Error encountered while trying to read collating table 
Error encountered while trying to write collating table 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
ACP file access failed 

ACP file create failed 

ACP file deaccess failed during $CLOSE 

ACP enter function failed 

ACP file extend failed 

ACP file or directory lookup failed 

ACP could not mark file for deletion 

Device positioning error 

Spool or submit of command file failed on $CLOSE 
Directory not found 

See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
File attributes read error 

File attributes write error 

Cannot close file 

Cannot deliver AST 

Assign channel system service request failed 

File read error 

ACP remove function failed 

Error detected while reading prolog 

QIO system service request failed 

File write error 

Error detected while writing prolog 

\llegal file attributes detected (file header corrupted) 
Error on write behind 

ENO system service request failed 


Network operation failed at remote node 


Table A—1 (Cont.) 


Hex Value 


00010144 
0001C14C 
0001C 154 
0001C15C 
0001C 164 
0001C16C 
00010174 
0001C17C 
0001C18C 
0001C194 


Status Code 


RMS$_SUPPORT 
RMS$_CRMP 
RMS$_DTFCFGFIL 
RMS$_REENT 
RMS$_ACC_RUJ 
RMS$_TMR 
RMS$_ACC_AlJ 
RMS$_ACC_BlJ 
RMS$_DTFDEFFIL 
RMS$_DTFREGFIL 
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Completion Status Hexadecimal Values and Codes 


Message Text 


Network operation not supported 

CRMPSC system service failed to map global buffers 

See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 
File could not be renamed and recovery failed; file has been lost 
See the VAX RMS Journaling Manual for details. 

SETIMR system service request failed 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
See the DECnet/SNA VMS Data Transfer Facility User’s Guide. 


Table A-—2 Descriptions of VMS RMS Completion Status Codes 


Status Code 


RMS$_ACC 


RMS$_ACS 
RMS$_ACC_AIJ 
RMS$_ACC_BlJ 
RMS$_ACC_RUJ 
RMS$_ACT 


RMS$_AID 


RMS$_ALN 


RMS$_ALO 


RMS$_ANI 
RMS$_AOP 
RMS$_ATR 


RMS$_ATW 
RMS$_.BADPHASE 


RMS$_BES 


RMS$_BKS 


Description 

File access error; the STV field contains an ACP error code. Take corrective 
action appropriate to the STV status code. 

Error in access control string of the node name. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 


File activity precludes operation; operation attempted during other file |/O. 
Modify the source program to detect and respond to this condition. 


Bad area identification number field in allocation XAB; the STV field contains the 
area ID. 


Invalid alignment boundary type in allocation XAB; the STV field contains the 
area ID. 


Incorrect allocation quantity; the value exceeds the maximum allowed (Create 
service) or exceeds the maximum allowed or is equal to zero (Extend service). 


Records in a magnetic tape file are not ANSI D format. 
Invalid allocation option in allocation XAB; the STV field contains the area ID. 


Read error on file header; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 


Write error on file header; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 


See the VAX RMS Journaling Manual for details. 


Bad escape sequence (terminals only, warning). Modify the source program to 
detect and recognize this condition or reenter the input specifying the correct 
escape sequence. 


Invalid bucket size in FAB or inconsistent record length. The bucket size 
specified in the FAB is larger than 63. If the bucket size is specified as zero, the 
maximum record size is too large. 


A-9 


VMS RMS Completion Status Codes 


Table A—2 (Cont.) 
Status Code 


RMS$_BKZ 
RMS$_BLN 


RMS$_BOF 


RMS$_BOGUSCOL 


RMS$_BUG 
RMS$_BUG_DAP 
RMS$_BUG_DDI 


RMS$_BUG_FLUSH_ 
JNL_FAILED 


RMS$_BUG_ 
RUCRECERR 


RMS$_BUG_RU_ 
ABORT_FAIL 


RMS$_BUG_RU_ 
ACTIVE 


RMS$_BUSY 


RMS$_CCF 


RMS$_CCR 


RMS$_CDA 


RMS$_CHG 
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Descriptions of VMS RMS Completion Status Codes 


Description 


Invalid bucket size in the allocation XAB; the STV field contains the area ID. 


Invalid value in block length field; this completion code is not available in the 
FABSL_STS/FAB$L__STV or RAB$L_STS/RAB$L_STV fields. 


Beginning of file detected (warning); you invoked the Rewind service or Space 
service at the beginning of the file. The STV field contains the number of blocks 
spaced. You may need to modify the source program to detect and respond to 
this condition. 


Either the collating sequence is missing, is inaccessible to RMS, or is in a format 
that RMS cannot interpret. This situation is typically created by an application 
program error. Verify that a valid NCS sequence is available to RMS. 


Internal VMS RMS error detected. Submit an SPR. 
Data Access Protocol error. Submit an SPR. 
Invalid default directory. Submit an SPR. 

See the VAX RMS Journaling Manual for details. 


See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 


FAB or RAB cannot be used because either a prior operation needs to complete 
before VMS RMS can use the FAB or RAB for the requested operation, or the 
user illegally called VMS RMS from executive mode at AST level or from kernel 
mode and interrupted another VMS RMS operation. Use multiple 1/O streams or 
use the Wait service as necessary. This completion code is not available in the 
FAB$L_STS/FAB$L_STV or RAB$L_STS/RAB$L_STV fields. 


For the $CLOSE service, an output file could not be closed successfully; user 
buffer identifies the file by its device ID and file ID. 


Cannot connect RAB; process has specified either a nonexistent or inaccessible 
RAB. This usually results from one of the following actions: 


e The program tried to do block I/O (setting RAB$V_BIO in RAB$L_ROP) with 
multistreaming (setting FAB$V_MSE bit in FAB$B_SHR). 


e The program tried to connect to multiple RABs to a FAB without first setting 
the FAB$V_MSE bit in the FAB$B_SHR field. 


e The program tried to use multistreaming with file access across DECnet. 


Cannot deliver AST; the STV field contains the STS value of the operation. The 
AST limit quota for the process has probably been exhausted. You need to 
increase the quota or decrease the level of AST activity. Take corrective action 
for the actual operation based on the STV value. 


The process tried to change a key value in a file that does not have the key 
change option. 


Table A—2 (Cont.) 


Status Code 
RMS$_CHK 


RMS$_CHN 


RMS$_COD 
RMS$_CONTROLC 


RMS$_CONTROLO 


RMS$_CONTROLY 


RMS$_CRC 


RMS$_CRE 


RMS$_CREATED 


RMS$_CRE_STM 
RMS$_CRMP 


RMS$_CUR 


RMS$_DAC 


RMS$_DAN 


RMS$_DEADLOCK 
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Description 


Index file bucket check byte mismatch; the bucket has been corrupted. The STV 
field contains the VBN of the bucket. This error can be caused by any of the 
following conditions: 


e The combination of a disk backed up using standalone BACKUP and files 
with the /NOBACKUP qualifier 


e Inadvertent modification of the file using block I/O or non-VMS RMS 
programs 


e Hardware, VMS RMS, or other system software errors 


Try to recreate the rest of the file. If the problem recurs and appears to be 
caused by VMS RMS or system software, submit an SPR. 


Channel assignment failure; the STV field contains a system error code. Take 
corrective action appropriate to the STV status code, if possible. 


Invalid type code in XAB; the STV field contains the XAB address. 


Operation completed under CTRL/C; terminal |/O may have been truncated 
(success). 


Operation completed under CTRL/O; terminal output may have been truncated 
(success). 


Operation completed under CTRL/Y; terminal 1/O may have been truncated 
(success). 


Network DAP level CRC failed on Close. The network link may be experiencing 
hardware errors. Retry the operation. 


ACP file creation failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code. 


File created with the FAB$V_CIF (create-if) option because the file was not 
found. If the file is found, it is opened (not created) and RMS$_NORMAL is 
returned (success). 


File created in stream format (success). 


For the Connect service, the requested number of global buffers is unobtainable; 
no global sections or an insufficient number of global pages or global page file 
entries were available to grant the requested number of global buffers. Reduce 
the number of global buffers requested in the FAB$W_GBC field and retry 

the Connect service, or wait until an orderly shutdown of the system can be 
arranged and increase the appropriate system generation parameters, then retry 
the operation. 


No current record; operation not immediately preceded by a successful Get or 
Find service. 


ACP file deaccess failed during Close. The file was deaccessed. The STV field 
contains an ACP error code. Take corrective action appropriate to the STV 
status code. 


Invalid data area number in key definition XAB; the STV field contains the key 
number. 


The VMS lock manager detected a deadlock. Modify the source program, if 
necessary. 
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Status Code 
RMS$_DEL 


RMS$_DELJNS 
RMS$_DEV 
RMS$_DFL 


RMS$_DIR 


RMS$_DME 


RMS$_DNA 
RMS$_DNF 


RMS$_DNR 


RMS$_DPE 


RMS$_DTFACC 
RMS$_DTFCDDREC 
RMS$_DTFCFGFIL 
RMS$_DTFCRE 
RMS$_DTFCVT 
RMS$_DTFDEFFIL 
RMS$_DTFQUASYN 
RMS$_DTFQUAVAL 
RMS$_DTFREGFIL 
RMS$_DTFSESEST 
RMS$_DTFSESTER 
RMS$_DTFTRATBL 
RMS$_DTFUNSTYP 
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Descriptions of VMS RMS Completion Status Codes 


Description 


RFA-accessed record deleted; the program attempted to access a previously 
deleted record. Modify the source program, if necessary. 


See the VAX RMS Journaling Manual for details. 
Bad device or inappropriate device type for operation. 


Data bucket fill size larger than bucket size specified in the key definition XAB; 
the STV field contains the key number. 


Error in directory name; the directory name specified incorrectly. For example, a 
directory or subdirectory name exceeded 39 characters in length, or the use of 
a logical name resulted in more than one directory name in the file specification. 
Verify the syntax of either the directory name in the file specification or the 
logical name, if applicable. 


Dynamic memory exhausted. Occurs only if the related 1/O segment in the 
control region is full and the file is either a direct access process-permanent file 
or the user has disallowed the use of the program region for |/O buffers to RMS. 


Invalid default file specification string address. 


Directory not found; specified directory name does not exist on the specified 
device. Verify that the device and directory are specified correctly. Create 

the directory on that device or use a different directory. When performing an 
Open service, consider using a search list logical name if the same file exists in 
multiple device/directory locations. The STV field contains a system error code. 
Take corrective action appropriate to the STV status code. 


Device not ready, not mounted, or unavailable. Make sure that the volume is 
physically loaded, that the device is ready, and that the DCL command MOUNT 
has been completed successfully. Check that the correct controller is set on the 
drive. Retry the operation. 


Device positioning error; magnetic tape improperly positioned. Examine the 
RAB$L_STV field for secondary status information; take corrective action 
appropriate to this information. Retry the operation. If this error persists, it may 
indicate a system software or hardware failure. Contact your system operator 
or manager. 


See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 
See the DECnet/SNA 


VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User's Guide. 
VMS Data Transfer Facility User’s Guide. 
VMS Data Transfer Facility User’s Guide. 


Table A—2 (Cont.) 
Status Code 


RMS$_DTFVERMIS 
RMS$_DTP 
RMS$_DUP 


RMS$_DVI 

RMS$_ENQ 
RMS$_ENT 
RMS$_ENV 


RMS$_EOF 


RMS$_ERRREADCOL 


RMS$_ERRWRITECOL 


RMS$_ESA 
RMS$_ESL 
RMS$_ESS 
RMS$_EXENOLM 


RMS$_EXP 


RMS$_EXT 


VMS RMS Completion Status Codes 


Descriptions of VMS RMS Completion Status Codes 


Description 


See the DECnet/SNA VMS Data Transfer Facility User's Guide. 
Invalid data type in key definition XAB; the STV field contains the key number. 


Duplicate key detected; key definition XAB key option flag not set to allow 
duplicate key values. 


Invalid device identification in the NAM block. 


Lock manager system service failed; the STV field contains a $ENQ system 
service error code. Take corrective action appropriate to the STV status code, 
if possible. 


ACP enter function failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 


Environment error; support for the VMS RMS service or selected option is not 
present in system. 


For Find or Get services, end of the file detected; the program attempted to read 
beyond the last record in the file. If necessary, modify the source program to 
detect and respond to the condition. 


For a Read (block I/O) service, end of the file detected. Checking for the logical 
end of the file is performed only for sequential file organization. If an RMS$_EOF 
error occurs, it implies that the first virtual block number specified is at or past 
the end of the file. If the RMS$_EOF error occurs during a transfer, the record 
size field is set to the number of bytes before the logical end of the file. For 
relative or indexed file organization, this status code indicates an attempt to read 
past the end of the currently allocated space. 


For a Write service (block I/O), end of the file detected for a sequential file; 
implies that the file could not be extended. Determine whether sufficient disk 
space is available on the disk device in use (use the DCL command SHOW 
DEVICE). If you do not have enough space, purge or delete files that are no 
longer needed; then retry the operation. 


An |/O error occurred when the program tried to read the file’s collating 
sequence. This is typically due to a hardware problem; otherwise, submit 
an SPR. 


An |/O error occurred when the program tried to write the sequence to the file. 
This is usually due to a hardware problem; otherwise, submit an SPR. 


Invalid expanded string area address in NAM block. 
Invalid expanded string length in NAM block. 
Expanded string area too short. 


Exceeded process enqueue limit. Reduce the number of locks held at one time 
and retry, or have the system manager increase this limit for your process. Log 
out and log in, and then retry the operation. 


File expiration date not yet reached; tried to overwrite magnetic tape files. If the 
file can be overwritten, remount the volume using the /OVERRIDE=EXPIRATION 
qualifier. (You must be the volume owner or have VOLPRO privilege to overwrite 
a volume.) Otherwise, use a different volume. 

ACP file extend failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 
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Table A—2 (Cont.) 
Status Code 


RMS$_FAB 


RMS$_FAC 


RMS$_FEX 


RMS$_FILEPURGED 


RMS$_FLG 


RMS$_FLK 


RMS$_FNA 
RMS$_FND 


RMS$_FNF 


RMS$_FNM 
RMS$_.FOP 
RMS$_FSZ 
RMS$_FTM 
RMS$_FUL 
RMS$_GBC 
RMS$_IAL 


RMS$_IAN 


RMS$_IBF 
RMS$_IBK 


RMS$_IDR 
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Descriptions of VMS RMS Completion Status Codes 


Description 


Invalid FAB; block identifier field incorrect. This completion code is not available 
in the FAB$L_STS/FAB$L_STV fields. 


Operation not allowed by the value set in the FAB$B_FAC field. For the Extend 
service, verify that the FAB$B_FAC field specifies put or update access for the 
file to be extended. Modify the source program if necessary. 


File already exists, not superseded; the program attempted to create or rename 
a file with the same file specification as an existing file. Choose a different file 
specification; delete the existing file (if a new file is to be created). For the 
Create service, consider using the FAB$L_FOP field FAB$V_SUP option to 
request that an existing file be superseded. 


This informational message indicates that the newly created file version 
exceeded the maximum number of versions allowed for the file; therefore, 
the oldest version is deleted. 


Invalid combination of values in key XAB$B_FLG field; the STV field contains 
the key number. (Example: XAB$V_CHG or XAB$V_NUL for primary key.) 


File currently locked by another user; the program attempted to create or open 
a file that is currently being accessed by another user, and the file was not 
accessed for sharing. Wait until the other user deaccesses the file and retry the 
operation. 

Invalid file specification string address in FAB. 


ACP file or directory lookup failed; error occurred during a directory search. The 
STV field contains an ACP error code. Take corrective action appropriate to the 
STV status code, if possible. 


File not found. Check the file specification and verify that the device, directory, 
file name, and file type are correct. If a logical name was specified, verify that 
the current equivalence name assigned to the logical name is correct. Verify that 
the correct volume is mounted and that the file was not inadvertently deleted. 


Syntax error in file name. 

Invalid file-processing options. 

Invalid fixed control area size in FAB (equal to 1 for print files). 
Network DAP file transfer mode does not permit operation. 
Device full; cannot create or extend file. 

Invalid global buffer count. 


Invalid argument list. Applies to the SYSSRMSRUNDWN, SYSS$SETDFPROT, 
and SYS$SETDDIR services. See the VMS System Services Reference Manual. 


Invalid index area number in key definition XAB; the STV field contains the key 
number. 


Invalid bucket format; STV contains bucket VBN. Submit an SPR. 


Bucket size of lowest level of index area number (KAB$B_LAN) not equal to that 
of specified index area number (XAB$B_IAN field) in key definition XAB; the 
STV field contains the key number. 


Invalid directory rename operation; attempted to rename a directory file into 
a directory tree that contained the directory file. The directory would then be 
inaccessible. 


Table A—2 (Cont.) 
Status Code 


RMS$_IDX 
RMS$_IFA 


RMS$_IFF 


RMS$_IFI 


RMS$_IFL 
RMS$_IMX 
RMS$_INVDRMSG 


RMS$_IOP 


RMS$_IRC 


RMS$_iSI 


RMS$_JND 
RMS$_JNS 
RMS$_JOP 
RMS$_KBF 
RMS$_KEY 


RMS$_KFF 
RMS$_KNM 


RMS$_KRF 


VMS RMS Completion Status Codes 


Descriptions of VMS RMS Completion Status Codes 


Description 
Index not initialized; internal VMS RMS error. Submit an SPR. 


Invalid file attributes; file header corrupted. Check the STV field for additional 
information. Take corrective action appropriate to the STV status code, if 
present. 


Invalid file attributes for requested access. Usually, this occurs when attempting 
to open an ANSI magnetic tape file for write access and the file has a nonzero 
value for its buffer offset value. VMS RMS does not allow the creation of a 
magnetic tape file with a nonzero buffer offset. You can, however, access such 
a file for read and write operations if you specify block I/O. 


Invalid internal file identifier in FAB; file already closed or not open (Close or 
Connect services), file already open or not closed (Create service), file not open 
(Display and Extend services), or file already open (other services). 


Index bucket fill size larger than bucket size specified in key definition XAB; the 
STV field contains the key number. 


More than one XAB of the same type or nondense XAB is present for the file; 
the STV field contains the XAB address. 


See the VAX RMS Journaling Manual for details. 


Invalid operation attempted; operation is one of following: (1) block I/O 
when record 1|/O access, (2) record 1/O when block 1/O access, (3) rewind of 
process-permanent file, (4) inappropriate device type or file organization. 


Invalid record encountered in file or invalid byte count field or control byte field 
contained in that record; the STV field contains the virtual block number for 
sequential and indexed files or the relative record number for relative files of the 
corrupted record. This error can be caused by the following conditions: 


e The combination of a disk backed up using standalone BACKUP and files 
with the /NOBACKUP qualifier 


e Inadvertent modification of files by block 1/O or non-VMS RMS programs 


e Hardware errors, VMS RMS errors, or other system software errors. 


For sequential and indexed files, try to recreate the rest of the file. For relative 
files, reinsert the bad record with the Put service using the RAB$L__ROP field 
RAB$V_UIF option. If this does not solve the problem, submit an SPR. 


Invalid internal stream identifier in RAB; record stream already connected 
(Connect service) or was not connected (other services). 


See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
Invalid key buffer address. 


Invalid record key for random operation to a relative file or invalid packed 
decimal key for an indexed file. 


Known file found; this code is reserved for DIGITAL usage only. 


Invalid key name buffer address in key definition XAB; the STV field contains 
the key number. 


Invalid key of reference in RAB$B_KRF field. 
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Table A—2 (Cont.) Descriptions of VMS RMS Completion Status Codes 





Status Code 
RMS$_KSI 


RMS$_KSZ 
RMS$_LAN 


RMS$_LEX 
RMS$_LNE 


RMS$_MBC 
RMS$_MKD 


RMS$_MRN 


RMS$_MRS 
RMS$_NAM 
RMS$_NEF 


RMS$_NET 


RMS$_NETFAIL 


RMS$_.NMF 


RMS$_NOD 
RMS$_NORMAL 
RMS$_NOVALPRS 


RMS$_NPK 
RMS$_OK_ALK 


RMS$_OK_DEL 


RMS$_OK__DUP 
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Description 

The size of the index buckets specified for the key must be large enough to hold 
at least two key values: the STV value contains the key of reference. 

Key size not equal to 4 (relative file) or key size too large (indexed file). 


Invalid index lowest-level-bucket area number in key definition XAB; the STV 
field contains the key number. 


Attempted to extend area containing an unused extent. 


Logical name error; an error was detected in file name processing. Usually this 
is caused by exceeding the maximum logical name translation count, typically 
when the equivalence string for a logical name is identical to the name itself. 
This error can also indicate a fatal error in logical name translation, or invalid 
syntax for a process-permanent file equivalence string. 


Invalid multiblock count. Must not be greater than 127. 


ACP could not mark file for deletion. The STV field contains an ACP error code. 
Take corrective action appropriate to the STV status code, if possible. 


Invalid value for maximum record number (negative) or relative key greater than 
maximum record number. 


Invalid value for maximum record size. 
Invalid or inaccessible NAM block. 


Attempted to use the Put service to a sequential file not positioned to the end 
of the file. 


Network operation failed at remote node; the STV field contains a DAP code. 
Take corrective action appropriate to the STV status code, if possible. 


Network operation failed at remote node; the STV field contains an FAL status 
code. Take corrective action appropriate to the STV status code, if possible. 


No more files found; the directory or volume set does not contain any more files 
that meet the file specification (wildcard operation). This is the normal status to 
indicate the end of a wildcard search operation. Modify the source program, if 
necessary, to detect and respond to this condition. 


Node name error. 
Operation successful (synonym for RMS$_SUC, success). 


Search service not preceded by a Parse service. Correct the source program to 
invoke the Parse service before invoking the Search service. 


No primary key defined in key definition XAB when creating an indexed file. 


Record is already locked; the program attempted to lock a previously locked 
record. No action is usually required, although this can depend on application 
requirements (success). 


Deleted record successfully accessed; a previously deleted record was read 
successfully. No action is usually required, although this can depend on 
application requirements (Success). 


Record inserted had duplicate key; the record was inserted successfully and had 
one or more key values that duplicated the values of other records (success). 


Table A—2 (Cont.) 
Status Code 
RMS$__OK_IDX 


RMS$_OK_LIM 


RMS$_LIMBO 
RMS$_NEXDR 
RMS$_NOTSAMEJNL 
RMS$_NRU 
RMS$_OK_NOP 


RMS$_OK_RLK 
RMS$_OK_RNF 
RMS$_OK—_RRL 


RMS$_OK—RULK 
RMS$_OK_WAT 


RMS$_ORG 
RMS$_PBF 
RMS$_PENDING 


RMS$_PES 


RMS$_PLG 
RMS$_PLV 
RMS$_POS 


RMS$_PRV 


RMS$_QUO 


VMS RMS Completion Status Codes 


Descriptions of VMS RMS Completion Status Codes 


Description 


Index update error occurred; the record was inserted successfully but an error 
occurred on index update, which could cause slow access to that record 
using that key path. Examine the value of the VMS RMS error in the RAB$L_ 
STV field. Take corrective action appropriate to the STV status code. File 
reorganization is recommended (success). 

Retrieved record exceeds specified key value; the retrieved record exceeds the 
specified key value when the RAB$L_ROP RAB$V_LIM option was specified. It 
was read successfully. No action is usually required, although this can depend 
on application requirements (success). 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

See the VAX RMS Journaling Manual for details. 

XAB not filled in for block 1/0; operation executed successfully when block 
|/O access was specified. One or more XABALL or XABKEY blocks were not 
filled. No action is usually required, although this can depend on application 
requirements (Success). 

Record locked but read anyway; the retrieved record was locked but was read 
successfully. No action is required (success). 

Nonexistent record successfully accessed; a nonexistent record was read 
successfully. No action is required (success). 


Record locked against read, but read anyway; a record locked against reading 
was read successfully. No action is required (success). 


See the VAX AMS Journaling Manual for details. 


Record locked after wait; the retrieved record was locked but has been read 
successfully after a wait period. No action is required (success). 


Unknown file organization. 
Invalid prompt buffer address. 


An asynchronous operation was initiated but is not yet completed; no action is 
required (Success). 


Partial escape sequence (terminals only, warning); the user buffer was filled 
before a complete escape sequence was entered. The remainder of the escape 
sequence is returned with the next input operation. Increase the size of the 
user buffer to allow escape sequences or modify the program, if necessary, to 
recognize and respond to this condition. 


Error in file prolog; file is corrupted. 
Prolog version unsupported. 


Invalid key position (greater than MRS) in key definition XAB; the STV field 
contains the key number. 


Insufficient privilege or file protection violation; the current process is denied 
access because of the file protection. Check the access rights associated 
with the file and change them if needed. If you are not the file owner or have 
insufficient privilege, request that the file owner change the protection. 


Error in quoted string. 
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Table A—2 (Cont.) 


Status Code 
RMS$_RAB 


RMS$_RAC 
RMS$_RAT 
RMS$_RBF 


RMSS$_REENT 


RMS$_REF 


RMS$_RER 


RMS$_REX 


RMS$_RFA 
RMS$_RFM 
RMS$_RHB 
RMS$_RLF 


RMS$_RLK 


RMS$_RMV 


RMS$_RNF 


RMS$_RNL 


RMS$_ROP 
RMS$_RPL 


RMS$_RRF 
RMS$_RRV 
RMS$_RSA 


RMS$_RSL 
RMS$_RSS 
RMS$_RST 


Descriptions of VMS RMS Completion Status Codes 


Description 


Not a valid RAB; block identifier field incorrect. This completion code is not 
available in the RAB$L_STS/RAB$L_STV fields. 


Invalid value in record access mode field of RAB. 
Record attributes invalid in FAB. 
Invalid record address. 


An attempt to use the ACP enter function for new file specification failed after 
the old file specification was removed, making it impossible to reenter the file 
specification. Examine the STV field for additional information. The file could 

not be renamed and recovery failed; the file has been lost. 


Invalid key of reference in XAB; key of reference was greater than number in file 
or equal to 255. 


File read error; the STV field contains a system error code. Take corrective 
action appropriate to the STV status code, if possible. 


Record already exists; while inserting a record into a relative file using random 
access mode, the specified record number is the same as an existing record; the 
new record was not written over the existing record. Note the condition. Modify 
the source program, if necessary, to detect and respond to this condition. You 
may want to specify the RAB$L__ROP field RAB$V_UIF option. 


Invalid record file address contained in RAB. 
Invalid record format. 
Invalid or inaccessible record header buffer. 


invalid or inaccessible related file block, or user has exceeded the limit of 255 
related file name blocks, or related file name blocks are linked circularly. 


Target record currently locked by another stream; the requested record cannot 
be accessed. Modify the source program, if necessary, to detect and respond 
to this condition. 


ACP remove operation failed. The STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 


Record not found; the requested record in an indexed or relative file either was 
never written or was deleted. Modify the source program, if necessary, to 
detect and respond to this condition. 


Record not locked (warning); no records were locked for this record stream 
when the operation was invoked. If necessary, modify the source program. 


Invalid record option. 


Error while reading prolog; the STV field contains an ACP error code. Take 
corrective action appropriate to the STV status code, if possible. 


See the VAX RMS Journaling Manual for details. 
Invalid RRV record encountered in indexed file; file may be corrupted. 


Record stream currently active (asynchronous operations); operation attempted 
while an 1/O request was outstanding for this record stream. 


Resultant string length field of NAM block invalid. 
Resultant string area size is too small. 


Invalid resultant string area address in NAM block. 


Table A—2 (Cont.) 


Status Code 


RMS$_RSZ 
RMS$_RTB 


RMS$_RUF 
RMS$_RUH 
RMS$_RU_ACTIVE 
RMS$_RUH 
RMS$_RVU 


RMS$_RUNDOWN 
RMS$_SEG 


RMS$_SEQ 


RMS$_SHR 


RMS$_SIZ 


RMS$_SPL 


RMS$_SQO 


RMS$_STR 


RMS$_SUC 


RMS$_SUP 


RMS$_SUPERSEDE 


RMS$_SUPPORT 


RMS$_SYN 


VMS RMS Completion Status Codes 


Descriptions of VMS RMS Completion Status Codes 


Description 


Invalid record size. 


Record too large for user’s buffer (warning); the record just returned was too 
large for the user buffer provided. The RAB$L_STV field contains the size of 
the record; the returned record is truncated to the size of the user buffer. Modify 
the source program by increasing the size of the user buffer. You can determine 
the size of the largest record in a file using the DCL command ANALYZE/RMS_ 
FILE or by examining the contents of the XABFHC field XABSW_LRL after 
opening the file with the XABFHC chained to the FAB. 


See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 


Error while updating RRVs; some paths to data may be lost. File reorganization 
is strongly recommended. 


Operation invalid during RMS rundown. 


Segmented key for key data type other than string. The STV field contains the 
key of reference. 


Primary key of record to be written is not equal to or greater than key of 
previous record and RAB$B_RAC field is set to RAB$V_SEQ. 


Invalid value in the file-sharing field of FAB. This condition can be caused by 
attempting to access a sequential file that cannot be shared. (Only relative files, 
indexed files, and sequential files with 512-byte fixed-length records can be 
shared.) 


Invalid key size specified in key definition XAB XAB$SB_SIZO through XAB$SB_. 
SIZ7 field; specified size exceeds maximum record size, not equal to defined 
length on binary and integer key data types, greater than 16 for packed decimal 
key data type, or equal to O for string or packed decimal. The STV field contains 
the key of reference. 


Spool or submit command file option to a Close service failed; the STV field 
contains a system error code. Take corrective action appropriate to the STV 
status code. 


Operation not sequential; file was opened with FAB$L_FOP field FAB$V_SQO 
option, random access is not permitted. 


User structure (FAB/RAB) became invalid during the execution of a file or record 
operation. This completion code is not available in the FAB$L_STS/FAB$L_ 
STV or RAB$L_STS/RAB$L_STV fields. 


Operation successful (synonym for RMS$_NORMAL). 


Network operation not supported; the STV field contains a DAP code. Take 
corrective action appropriate to the STV status code, if possible. 


Created file supersedes existing version of same file; no action is required 
(success). 


Network operation not supported; the STV field contains a FAL/DAP status 
code. Take corrective action appropriate to the STV status code, if possible. 


Syntax error in file specification. 
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Status. Code 
RMS$_SYS 


RMS$_TMO 


RMS$_TMR 
RMS$_TNS 


RMS$_TOWDR 
RMS$_TRE 
RMS$_TYP 
RMS$_UBF 
RMS$_UNKRUFAC 
RMS$_UPI 


RMS$_USZ 
RMS$_VER 
RMS$_WBE 


RMS$_WCC 
RMS$_WER 
RMS$_WLD 
RMS$_WLK 
RMS$_WPL 


RMS$_WRTJNL _AIJ 
RMS$_WRTJNL _BlJ 
RMS$_WRTJNL _RUJ 
RMS$_XAB 


RMS$_XNF 
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Description 


Error in system QIO directive; the STV field contains the directive or QIO status 
code. Take corrective action appropriate to the STV status code, if possible. 


Timeout period expired (terminal input, locked record, or mailbox devices, 
warning); the Find, Get, or Read service did not complete. For terminal and 
mailbox devices, the characters (if any) received before the timeout period 
expired are discarded. For disk record operations, the requested record was 
locked for the entire timeout period and was not read. Modify the source 
program, if necessary, to detect this condition and retry the requested service. 


SETIMR system service request failed. 


Terminator not seen (terminals only; warning); the terminal Get service 
terminated when the user buffer was filled to capacity, before a terminator 
sequence was encountered. Subsequent Get services can retrieve additional 
characters from that input line, including the terminator character sequence, 
which is not in the current user buffer. Modify the source program to detect 
and respond to this situation or provide a user buffer large enough to contain an 
entire input line including the terminator character sequence. 


See the VAX RMS Journaling Manual for details. 
Index tree error; file is corrupted. 

Error in file type. 

Invalid user record buffer address. 

See the VAX RMS Journaling Manual for details. 


The FAB$B_SHR field FAB$V_UPI option not set when file sharing FAB$L_FOP 
field FAB$V_BIO or FAB$V_BRO option was set. 


Invalid user record area size. 
Error in version number. 


Error writing behind; the STV field contains a system error code. Take 
corrective action appropriate to the STV status code, if possible. 


Invalid wildcard context value. Verify that the NAM block has not been 
inadvertently modified between VMS RMS service calls. — 


File write error; the STV field contains a system error code. Take corrective 
action appropriate to the STV status code, if possible. 


Invalid wildcard operation. 


Device currently write-locked when write access was attempted. Verify the 
status of the device; reset the write-lock switch, if necessary. Notify the system 
operator if the error cannot be corrected. 


Error while writing prolog; the STV field contains an ACP or system error code. 
Take corrective action appropriate to the STV status code, if possible. 


See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 
See the VAX RMS Journaling Manual for details. 


Not a valid XAB, not readable or writable, invalid code or length; the STV field 
contains the XAB address. 


Could not locate XAB needed for this operation. Modify the source program 
to include the XAB and specify the address of the XAB in the FAB$L_XAB or 
RABS$L_XAB field. 


B 


RMS Control Block Macros 


This appendix lists the format of each VMS RMS control block macro and 
includes special syntax notes that differ from the rules provided in Part I. 
Note that in this appendix the use of the term “macro” refers to a VAX 
MACRO macro. 


VMS RMS Control Block Macros 





$FAB 
The $FAB macro allocates storage for a FAB and initializes certain FAB 
fields with defaults and user-specified values. No value is returned for this 
assembly-time operation. 

FORMAT $FAB ALO =allocation-quantity, 


BKS = bucket-size, 
BLS = block-size, 
CHAN_MODE = channel-access-mode 
CTX = user-context-value, 
DEQ = extension-quantity, 
DNA = default-filespec-address, 
DNM = <filespec> , 
DNS = default-filespec-string-size, 
FAC =<BIO BRO DEL GET PUT TRN UPD> , 
FNA = filespec-string-address, 
FNM =<filespec> , 
FNS = filespec-string-size, 

<CBT CIF CTG DFW DLT 

MX V NAM NEF NFS OFP 
FOP = POS RCK RWC RWO SCF 

SPL SQO SUP TEF TMD 

TMP UFO WCK> , 
FSZ = header-size, 
GBC = global-buffer-count, 
LNV_MODE = logical-name-translation- 

access-mode, 
MRN = maximum-record-number, 
MRS = maximum-record-size, 
NAM = nam-address, 
IDX 
ORG = | REL 
SEQ 


CR 
rar | <BLK FTN> ; 
PRN 
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FIX 

STM 

STMCR 
RFM=%\ STMLF 7. 

UDF 

VAR 


VFC 
RTV = window-size, 


SHR = <DEL GET MSE NIL PUT UPD UPI> , 
XAB = xab-address 





ARGUMENTS 


For a description of the contro] block fields that correspond to the $FAB 
macro arguments, see Chapter 5. In some cases, specific default values are 
assigned automatically when you omit an argument. If there is no specific 
default, VMS RMS uses a default value of 0. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 


Note that multiple arguments can be specified for the FAC, FOP, RAT, and 
SHR keywords, but the arguments must be enclosed within left angle ( <) 

and right angle (> ) brackets. The DNM and FNM arguments must also be 
delimited by these signs. 


The DNM and FNM arguments contain ASCII characters and have no 
corresponding field in the FAB. If the DNM argument is present, VMS RMS 
places its appropriate address and size in the FAB$L_DNA and FAB$B_ 
DNS fields. Similarly, if the FNM argument is present, VMS RMS places its 
appropriate address and size in the FAB$L_FNA and FAB$B_FNS fields. 
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$FAB_STORE 
The $FAB_STORE macro moves user-specified values into fields of the 
specified FAB. The expanded $FAB_STORE code executes at run time 
on a previously initialized (allocated) FAB, in contrast to the $FAB macro, 
which initializes the FAB at assembly time. The $FAB_STORE macro must 
reside in a code program section. 

FORMAT $FAB_STORE fab = fab-adadress, 


ALQ = #allocation-quantity, 
BKS = #bucket-size, 
BLS = #block-size, 
CHAN_MODE = #channel-access-mode 
CTX = user-context-value, 
DEQ = #extension-quantity, 
DNA = default-filespec-address, 
DNS = #default-filespec-string-size, 
FAC =<BIO BRO DEL GET PUT TRN 
UPD> , 
FNA = filespec-string-address, 
FNS = #filespec-string-size, 
<CBT CIF CTG DFW DLT 
MXV NAM NEF NFS OFP 
FOP = POS RCK RWC RWO SCF 
SPL SQO SUP TEF TMD 
TMP UFO WCK> , 
FSZ = #header-size, 
GBC = #global-buffer-count, 
LNM_MODE = #logical-name- 
translation-access-mode, 
MRN = #maximum-record-number, 
MRS = #maximum-record-size, 
NAM = nam-address, 
IDX 
ORG = REL 
SEQ 


CR 
RAT <BLK FTN> , 
PRN 
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FIX 

STM 

STMCR 
RFM=< STMLF }. 

UDF 

VAR 


VFC 
RTV=#window-size, 


SHR =<DEL GET MSE NIL PUT UPD 
UPI> , 
XAB = xab-address 





ARGUMENTS 


For a description of the control block fields that correspond to the $FAB_ 
STORE macro arguments, see Chapter 5. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The FAB argument fab-address is required for the $FAB_STORE macro and 
is not present for the $FAB macro. Conversely, the DNM argument filespec 
and FNM argument default-filespec are not available for the $FAB_STORE 
macro, although you can use the DNA/DNS and FNA/FNS arguments to 
specify file specifications at run time. 


Note that RO is usually used by the $FAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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S$NAM 


The $NAM macro allocates storage for a NAM block and initializes certain 
NAM fields with default values and user-specified values. No value is 
returned for this assembly-time operation. 





FORMAT $NAM_ ESA = expandea-string-address, 
ESS = expandea-string-size, 
NOP =< NOCONCEAL PWD 
SRCHXABS SYNCHK> , 
RLF = related-file-nam-block-address, 
RSA = resultant-string-address, 
RSS = resultant-string-size 





ARGUMENTS For a description of the control block fields that correspond to the $NAM 
macro arguments, see Chapter 6. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 


Note that multiple arguments can be specified for the NOP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle (> ) 
brackets. 
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S$NAM_STORE 


The $NAM_STORE macro moves user-specified values into fields of the 
specified NAM block. The expanded $NAM_STORE code executes at 
run time on a previously initialized (allocated) NAM block, in contrast to 
the $NAM macro, which initializes a NAM block at assembly time. The 
$NAM_STORE macro must reside in a code program section. 





FORMAT 


S$NAM_STORE NAM=nam-address, 
| DID = #directory-identification, 

DVI = #device-identification, 

ESA = expanded-string-address, 

ESS = #expandeda-string-size, 

FID = #file-identification, 

Nop = < NOCONCEAL PWD 
SRCHXABS SYNCHK> , 

RLF = related-file-nam-block-address, 

RSA = resultant-string-address, 

RSS = #resultant-string-size 





ARGUMENTS 


For a description of the control block fields that correspond to the $NAM_— 
STORE macro arguments, see Chapter 6. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The NAM argument nam-address is required for the $NAM_—STORE macro 
and is not present for the $NAM macro. Also, the $NAM—STORE argument 
fields below are not available for the $NAM macro. 


e The DID argument directory-identification sets the NAM$W_DID field, 
which is a 3-word field used when the FAB$L_FOP field FABSV_NAM 
option is set. This argument is usually specified by its symbolic address. 
If a register is used to contain a value for the NAM$W_DID field, do 
not use R12, because two contiguous registers must be used to contain 
the value of this 3-word field. Note that you cannot use the byte, word, 
or longword displacements for an offset, or for indexed or deferred 
addressing. 


e The DVI argument device-identification sets the NAM$T_DVI field, 
which is a 16-byte field used when the FAB$L_FOP field FAB$V_NAM 
option is set. This argument must be passed by its symbolic address. A 
register must not be specified to contain a value for this argument. 
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e The FID argument file-identification sets the NAM$W_FID field, which 
is a 3-word field used when the FAB$L_FOP field FAB$6V_NAM option 
is set. This argument is specified by its symbolic address. If a register 
is used to contain a value for the NAM$W_FID field, do not use R12, 
because two contiguous registers must be used to contain the value of 
this 3-word field. Note that you cannot use the byte, word, or longword 
displacements for an offset, or for indexed or deferred addressing. 


Note that RO is usually used by the $NAM_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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The $RAB macro allocates storage for a RAB and initializes certain RAB 
fields with defaults and user-specified values. You cannot use this macro 
within a sequence of executable instructions. No value is returned for this 
assembly-time operation. 





FORMAT 


$RAB_ BKT = bucket-code-number, 

CTX = user-context-value, 
FAB = fab-address, 
KBF = key-buffer-address, 
KRF = key-of-reference-number, 
KSZ = key-size, 
MBC = multiblock-count-number, 
MBF = multibuffer-count-number, 
PBF = prompt-buffer-address, 
PSZ = prompt-buffer-size, 

KEY 
RAC = | RFA ; 


SEQ 

RBF = record-buffer-address, 

RHB = record-header-buffer-address, 
<ASY BIO CCO CVT EOF EONXT 
ETOFDL KGE KGT LIMLOA 

ROP =LOC NLK NXR NXT PMT PTA 
RAH REA RLK RNE RNF RRL 
TMO TPT UIF ULK WAT WBH-> , 

RSZ = record-size, 

TMO = time-out-number-of-seconds, 

UBF = user-record-buffer-address, 

USZ = user-record-buffer-size, 

XAB = xab-address 
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$RAB 





ARGUMENTS 
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For a description of the control block fields that correspond to the $RAB 
macro arguments, see Chapter 7. In some cases, specific default values are 
assigned automatically when you omit an argument. These specific defaults 
are noted in the text that explains each field in Chapter 7. If there is no 
specific default, VMS RMS uses a default value of 0. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 


Note that multiple arguments can be specified for the ROP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle 
(> ) brackets. Note too that the arguments KGE and EQNXT are logically 
synonymous, as are the arguments KGT and NXT. 
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$RAB_STORE 


The $RAB_STORE macro moves user-specified values into fields of the 
specified RAB. The expanded $RAB_STORE code executes at run time 
on a previously initialized (allocated) RAB, in contrast to the $RAB macro, 
which initializes the RAB at assembly time. The $RAB_STORE macro 
must reside in a code program section. 





FORMAT 


S$RAB_STORE RAB=rab-address, 
BKT = #bucket-code-number, 
CTX = user-context-value, 
FAB = fab-address, 
KBF = key-buffer-address, 
KRF = #key-of-reference-number, 
KSZ = #key-size, 
MBC = #multiblock-count-number, 
MBF = #multibuffer-count-number, 
PBF = prompt-buffer-address, 
PSZ = #prompt-buffer-size, 

KEY 

RAC = RFA 


SEQ 
RBF = record-buffer-address, 
RFA = #recora-file-address, 
RHB = record-header-buffer-address, 
<ASY BIO CCO CVT 
EOF EQNXT ETO FDL 
KGE KGT LIM LOA 
ROP= LOC NLK NXR NXT 
PMT PTA RAH REA 
RLK RNE RNF RRL 
TMO TPT UIF ULK 
WAT WBH> , 
RSZ = #record-size, 
TMO = #time-out-number-of- 
seconds, 
UBF = user-record-buffer-address, 
USZ = #user-record-buffer-size, 
XAB = xab-address 
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ARGUMENTS 
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For a description of the control block fields that correspond to the $RAB_ 
STORE macro arguments, see Chapter 7. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The RAB argument rab-address is required for the $RAB_STORE macro 
and is not present for the $RAB macro. Also, the RFA argument record- 
file-address is a value (not an address), and it is not available for the $RAB 
macro. The value for the 3-word RAB$W_RFA field must be set before each 
RFA record access. 


This argument is specified by its symbolic address. If a register is used to 
contain a value for the RAB$W_RFA field, do not use R12, because two 
contiguous registers must be used to contain the value of this 3-word field. 
Note that you cannot use the byte, word, or longword displacements for an 
offset, or for indexed or deferred addressing. 


Note that multiple arguments can be specified for the ROP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle 

(> ) brackets. Note too, that the arguments KGE and EQNXT are logically 
synonymous as are the arguments KGT and NXT. 


Note that RO is usually used by the $RAB_STORE macro; thus, RO is not 
preserved and does not contain a return status. 


$XABALL 
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The $XABALL macro allocates and initializes an XABALL, which allows 
extended control of file disk space allocation, both for initial allocation and 
later extension. No value is returned for this assembly-time operation. 








FORMAT $XABALL AID = area-identification-number, 
ANY 
CYL 
ALN= LBN j 
RFI 
VBN 
ALO = allocation-quantity, 
_<CBTCTG 
nor HRD ONC> , 
BKZ = bucket-size, 
DEQ = extension-quantity, 
LOC = location-number, 
NXT = next-xab-address, 
RFl=<f(1), (2), (3)>, 
VOL = volume-number 
ARGUMENTS For a description of the control block fields that correspond to the $XABALL 


macro arguments, see Chapter 8. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 


Note that multiple arguments can be specified for the AOP keyword, but 
the arguments must be enclosed within left angle ( <) and right angle (> ) 
brackets. 
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$XABALL_—STORE | 


The $XABALL_STORE macro moves user-specified values into fields of 
the specified XABALL. The expanded $XABALL_STORE code executes 
at run time on a previously initialized (allocated) XABALL, in contrast to 
the $XABALL macro, which initializes an XABALL at assembly time. The 
$XABALL_STORE macro must reside in a code program section. 








FORMAT $XABALL_STORE XAB= xaball-address, 
: AID = #area-identification-number, 
ANY 
CYL 
ALN= LBN ; 
RFI 
VBN 
ALO = #allocation-quantity, 
_<CBTCTG 
ee HRD ONC> , 
BKZ = #bucket-size, 
DEQ = #extension-quantity, 
LOC = #location-number, 
NXT = next-xab-address, 
RFI = #related-file-identification, 
VOL = #volume-number 
ARGUMENTS For a description of the control block fields that correspond to the $XABALL — 


STORE macro arguments, see Chapter 8. 


Arguments fall into several categories: value, address, keyword, and the 
address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros 
are described in Chapter 3. 


The XAB argument xaball-address is required for the $XABALL_STORE 
macro and is not present for the $XABALL macro. Also, the RFI argument 
related file identification sets the XAB$W_RFI field, which is a 3-word field 
used when the XAB$B_ALN field XAB$V_RFI option is set. This argument 
is usually specified by its symbolic address. If a register is used to contain 

a value for the XAB$W_RFI field, do not use R12, because two contiguous 
registers must be used to contain the value of this 3-word field. Note that 
you cannot use the byte, word, or longword displacements for an offset, or 
for indexed or deferred addressing. 


Note that RO is usually used by the $XABALL_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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The $XABDAT macro allocates and initializes an XABDAT. No value is 
returned for this assembly-time operation. 
FORMAT $XABDAT EDT =date-time, 


NXT = next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABDAT 
macro arguments, see Chapter 8. 


Rules applicable to arguments are described in Chapter 3. 
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$XABDAT_STORE 


The $XABDAT_STORE macro moves user-specified values into fields of 
the specified XABDAT. The expanded $XABDAT_STORE code executes 
at run time on a previously initialized (allocated) XABDAT, in contrast to 
the $XABDAT macro, which initializes an XABDAT at assembly time. The 
$XABDAT_STORE macro must reside in a code program section. 








FORMAT $XABDAT_STORE XAB= xabdat-adaress, 

CDT = #creation-date-time, 

EDT = #expiration-date-time, 

RDT = #revision-date-time, 

RVWN = #revision-number, 

NXT = next-xab-address 
ARGUMENTS For a description of the control block fields that correspond to the $XABDAT_ 
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STORE macro arguments, see Chapter 8. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabdat-address is required for the $XABDAT_STORE 
macro and is not present for the $XABDAT macro. Also, the arguments 
below differ from the general rules. 


¢ The CDT argument creation-date-time sets the XAB$Q_—CDT field, 
which is a quadword field. However, if a register is used to contain a 
literal value for the XAB$Q__CDT field, do not use R12, because two 
contiguous registers must be used to contain the value of this quadword 
field. 


e The EDT argument expiration-date-time sets the XAB$Q_EDT field, 
which is a quadword field. The rules for the other time fields (see above) 
also apply to this one. 


¢ The RDT argument revision-date-time sets the XAB$Q_—CDT field, 
which is a quadword field. The rules for the other time fields (see above) 
also apply to this one. 


Note that RO is usually used by the $XABDAT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABFHC 


The $XABFHC macro allocates and initializes an XABFHC. No value is 
returned for this assembly-time operation. 





FORMAT. $XABFHC NXT =next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABFHC 
macro arguments, see Chapter 10. 


Rules applicable to arguments are described in Chapter 3. 


B-17 


VMS RMS Control Block Macros 
$XABFHC_STORE 


$XABFHC_STORE 


The $XABFHC_STORE macro moves user-specified values into fields of 
the specified XABFHC. The expanded $XABFHC_STORE code executes 
at run time on a previously initialized (allocated) XABFHC, in contrast to 
the $XABFHC macro, which initializes an XABFHC at assembly time. The 
$XABFHC_STORE macro must reside in a code program section. 





FORMAT S$XABFHC_STORE XAB= xabfhc-address, 
NXT = next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABFHC_ 
STORE macro arguments, see Chapter 10. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabfhc-address is required for the $XABFHC_STORE 
macro and is not present for the $XABFHC macro. 


Note that RO may be used by the $XABFHC_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABITM 
The $XABITM macro allocates and initializes an XABITM. No value is 
returned for this assembly-time operation. 
FORMAT $XABITM_ /TEMLIST = item-list-address, 
MODE = sensemode \ 
setmode ‘ 


NXT = next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABITM 
macro arguments, see Chapter 11. 


Rules applicable to arguments are described in Chapter 3. 


ITEMLIST defaults to 0 but a valid pointer must be specified when you use a 
$XABITM macro. MODE defaults to sensemode. 
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$XABKEY 

S$XABKEY 
The $XABKEY macro allocates and initializes an XABKEY. No value is 
returned for this assembly-time operation. 

FORMAT $XABKEY COLTBL = collating-table-address, 


DAN = data-bucket-area-number, 
DFL = data-bucket-fill-size, 
BN2 


DBN2 

BN4 

DBN4 

BN8 

DBN8& 

IN2 

DIN2 
pTp-} IN4 

DIN4 

IN8 

DIN8& 

COL 

DCOL 

PAC 

DPAC 

STG 

DSTG 

<€HG DAT_NCMPR DUP 
FLG= IDX_NCMPR 
KEY_NCMPR NUL> , 

IAN = index-bucket-area-number, 
IFL = index-bucket-file-size, 
KNM = key-name-buffer-address, 
LAN = lowest-level-index-area-number, 
NUL = null-key-value, 
NXT = next-xab-address, 
POS =<position,...>, 
PROLOG = prolog-level, 
REF = key-of-reference-value, 
SIZ = <size,...> 
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ARGUMENTS 


For a description of the control block fields that correspond to the $XABKEY 
macro arguments, see Chapter 13. 


Arguments fall into three categories: values, addresses, and keywords. Rules 
applicable to these argument categories are described in Chapter 3. 


Multiple arguments can be specified for the FLG keyword, but the arguments 
must be enclosed within left angle ( <<) and right angle (> ) brackets. 
Defaults are applied to the XAB$B_FLG field only if no FLG argument is 
specified. Consider the following: 


KEY_1: $XABKEY REF = 1, POS = 0, SIZ = 10 


This line specifies the key for alternate index 1. Therefore the macro defaults 
the XAB$B_FLG field to allow duplicates and changes (the default for 
alternate keys). However, if an FLG argument is explicitly specified, the 
results are different, as shown below. 


KEY_2: $XABKEY REF = 1, POS = 0, SIZ = 10, FLG = CHG 


In this case, the CHG bit is set in the XAB$B_FLG field and the DUP bit 
remains clear, to disallow duplicates on this key. 


Depending on whether the key being defined is simple or segmented, you 
would use one of the following two formats for the POS and SIZ arguments: 


POS = position 


SIZ = size 


or 
POS ~<positiono,..., position7> 
SIZ =<sizeO,..., size7> 


You must include the angle brackets for multiple argument key positions and 
sizes. 
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$XABKEY_STORE 


The $XABKEY_STORE macro moves user-specified values into fields of 
the specified XABKEY. The expanded $XABKEY_STORE code executes 
at run time on a previously initialized (allocated) XABKEY, in contrast to 
the $XABKEY macro, which initializes the XABKEY at assembly time. The 
$XABKEY_STORE macro must reside in a code program section. 





FORMAT $XABKEY_STORE XAB= xabkey-address, 
COLTBL = #collating-table-address, 
DAN = #data-bucket-area-number, 
DFL = #data-bucket-fill-size, 
BN2 


DBN2 
BN4 
DBN4 
BN8 
DBN8 
IN2 
DIN2 . 
pTp=.IN@ 
DIN4. 
IN8 
DIN8 
COL 
DCOL 
PAC 
DPAC 
STG 
DSTG 
<CHG DAT_NCMPR 
FLG = DUP IDX_NCMPR 
KEY_NCMPR NUL> , 
IAN = #iINdex-bucket- 
area-number, 
IFL = #index-bucket-fill-size, 
KNIV = Key-name-buffer- 
address, 
LAN = #lowest-level-index- 
area-number, 
NUL = #null-key-value, 
NXT = next-xab-adadress, 
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POS = <position,...>, 
PROLOG = #prolog-level, 

REF = #key-of-reference-value, 
SIZ = <size,...> 





ARGUMENTS 


For a description of the control block fields that correspond to the $XABKEY_ 
STORE macro arguments, see Chapter 13. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabkey-address is required for the $XABKEY_STORE 
macro and is not present for the $XABKEY macro. The POS and SIZ 
arguments can be either symbolic addresses or a list of up to eight 

values, where each value must be preceded by a number sign (#), and 

the entire list must be enclosed within left angle and right angle brackets 

( <#value,...,4#value> ). The number of POS and SIZ values must be equal. 
Alternatively, each POS and SIZ value can be specified as an argument, using 
the following form: 


POSO = #value, POSi = #value, ..., POS7 = #value 
SIZO = #value, SIZi = #value, ..., SIZ7 = #value 


Note that RO is usually used by the $XABKEY_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABPRO 


The $XABPRO macro allocates and initializes an XABPRO. No value is 
returned for this assembly-time operation. 





FORMAT $XABPRO ACLBUF = ACL-buffer-address, 

ACLCTX =<ACL-context> , 

ACLSIZ = ACL-buffer-size, 

MTACC = magnetic-tape- 
accessibility, 

NXT = next-xab-address, 

_ <system, owner, 

i group, world> , 

PROT_OPT =<PROPAGATE> , 

UIC = <group, member> 





ARGUMENTS For a description of the control block fields that correspond to the $XABPRO 
macro arguments, refer to Chapter 14. 


Rules applicable to arguments are described in Chapter 3. 


For the MTACC argument, an ASCII radix indicator is required. For example, 
the letter Z is entered as the accessibility character with the following macro 
expression: 


$XABPRO MTACC = “A/Z/ 


In this example, the circumflex (*) followed by an uppercase A (*A) indicates 
that ASCII text follows. The two slashes (//) delimit the ASCII text. VMS 
RMS converts all lowercase characters to uppercase. No other modification is 
made. 


For the PRO argument, the angle brackets are required syntax, and each 
user class must be separated from the others by a comma. When you omit a 
class to use the default protection, you must retain the comma to indicate the 
omission, unless no other class follows. 


To allow all system users read and write access, use the default file protection 
for the file owner (by omission), allow group users read access, and use the 
default for world users, you would specify <RW,,R> . You may specify all, 
some, or none of the access characters and place multiple characters in any 
order, for each user class. 


VMS RMS Control Block Macros 
$XABPRO 


Here is a listing of the user classes together with the letters used to represent 
them: 


e R—read access 
e W—write access 
e E—execute access 


e D—delete access 


The absence of a code specifies that the access associated with the code is 
denied to the user. 


A user is granted the maximum number of access rights for each of the classes 
to which he belongs. 


For the UIC argument, the value for the group item must be in the range 

of 0 to 37777; the value for the member item must from 0 to 177777. Note 
that the maximum values (37777 and 177777) are reserved for DIGITAL use 
only. The group number and member number must be enclosed within angle 
brackets, placed in the order <group,member> , and be separated by a 
comma. Each number is interpreted as an octal number. 
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$XABPRO_STORE 


The $XABPRO_STORE macro moves user-specified values into fields of 
the specified XABPRO. The expanded $XABPRO_STORE code executes 
at run time on a previously initialized (allocated) XABPRO, in contrast to 
the $XABPRO macro, which initializes an XABPRO at assembly time. The 
$XABPRO_STORE macro must reside in a code program section. 





FORMAT 


$XABPRO_STORE XAB= xabpro-address, 
ACLBUF = ACL-buffer-address, 
ACLCTX = #<ACL-context> , 
ACLSIZ = #ACL-buffer-size, 
MTACC = *Magnetic-tape- 
accessibility, 
NXT = next-xab-address, 
_<system, owner, 
PAO group, world> , 
PROT_OPT =<PROPAGATE> , 
UIC = #uic-value 





ARGUMENTS 
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For a description of the control block fields that correspond to the $XABPRO_ 
STORE macro arguments, see Chapter 14. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabpro-address is required for the $XABPRO_STORE 
macro and is not present for the $XABPRO macro. Also, the following 
arguments do not comply with the general rules: 


e The PRO argument (file protection) can be either a symbolic address 
or a list of keyword values. If you specify a list of keywords, it 
must be enclosed within left angle ( <) and right angle (> ) brackets 
and the number sign (#) must be omitted; for example, PRO = 

<RWED,RWED,R,R> . 


¢ The UIC argument (group,member) can be either a symbolic address 
or a list of two data values. If the data values are constants, they must 
be specified with an octal radix without a preceding number sign (#). 
This argument can be passed by its symbolic address or by using a VAX 
MACRO expression. 


Note that RO is usually used by the $XABPRO_STORE macro; thus, RO is not 
preserved and does not contain a return status. 


VMS RMS Control Block Macros 
$XABRDT 


$XABRDT 


The $XABRDT macro allocates and initializes an XABRDT. No value is 
returned for this assembly-time operation. 





FORMAT $XABRDT NXT =next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABRDT 
macro argument, see Chapter 15. 


Rules applicable to arguments are described in Chapter 3. 
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$XABRDT_STORE 


The $XABRDT_STORE macro moves user-specified values into fields of 
the specified XABRDT. The expanded $XABRDT_STORE code executes 
at run time on a previously initialized (allocated) XABRDT, in contrast to 
the $XABRDT macro, which initializes the XABRDT at assembly time. The 
$XABRDT_STORE macro must reside in a code program section. 








FORMAT $XABRDT_STORE XAB= xabrat-adoress, 

RDT = #revision-date-time, 

RVN = #revision-number, 

NXT = next-xab-address 
ARGUMENTS For a description of the control block fields that correspond to the $XABRDT_ 


STORE macro arguments, see Chapter 15. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabrdt-address is required for the $XABRDT_STORE 
macro and is not present for the $XABRDT macro. Also, the RDT argument 
revision-date-time and RVN argument revision-number are not present 
in the $XABRDT macro. The RDT argument revision-date-time is usually 
passed by its symbolic address. However, if a register is used to contain a 
value for the XAB$Q_—RDT field, do not use R12, because two contiguous 
registers must be used to contain the value of this quadword field. 


Note that RO is usually used by the $XABRDT_STORE macro; thus, RO is not 
preserved and does not contain a return status. 
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$XABSUM 


The $XABSUM macro allocates and initializes an XABSUM. No value is 
returned for this assembly-time operation. 





FORMAT $XABSUM_ NXT =next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABSUM 
macro argument, see Chapter 17. 


Rules applicable to arguments are described in Chapter 3. 
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$XABSUM_STORE 


The $XABSUM_STORE macro moves user-specified values into fields of 
the specified XABSUM. The expanded $XABSUM_STORE code executes 
at run time on a previously initialized (allocated) XABSUM, in contrast to 
the $XABSUM macro, which initializes the XABSUM at assembly time. 
The $XABSUM_STORE macro must reside in a code program section. 








FORMAT S$XABSUM_STORE XAB= xabsum-address, 
NXT = next-xab-address 
ARGUMENTS For a description of the control block fields that correspond to the 
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$XABSUM_STORE macro arguments, see Chapter 17. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabsum-address is required for the $XABSUM_STORE 
macro and is not present for the $XABSUM macro. 


Note that RO may be used by the $XABSUM_—STORE macro; thus, RO is not 
preserved and does not contain a return status. 


VMS RMS Control Block Macros 
$XABTRM 





$XABTRM 
The $XABTRM macro allocates and initializes an XABTRM. No value is 
returned for this assembly-time operation. 

FORMAT $XABTRM_ /TMLST = item-list-address, 


ITMLST_LEN = item-list-length, 
NXT = next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the $XABTRM 
macro arguments, see Chapter 18. 


Rules applicable to arguments are described in Chapter 3. 
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$XABTRM_STORE 


The $XABTRM_STORE macro moves user-specified values into fields of 
the specified XABTRM. The expanded $XABTRM_STORE code executes 
at run time on a previously initialized (allocated) XABTRM, in contrast to 
the $XABTRM macro, which initializes an XABTRM at assembly time. The 
$XABTRM_STORE macro must reside in a code program section. 





FORMAT SXABTRM_STORE XAB= xabtrm-adaress, 
ITMLST = item-list-address, 
ITMLST_LEN = #item-list-length, 
NXT = next-xab-address 





ARGUMENTS For a description of the control block fields that correspond to the 
$XABTRM_—STORE macro arguments, see Chapter 18. 


Arguments fall into several categories: values, addresses, keywords, and 

the address of the control block to receive the specified arguments. Rules 
applicable to these argument categories for the control block store macros are 
described in Chapter 3. 


The XAB argument xabtrm-address is required for the $XABTRM—STORE 
macro and is not present for the $XABTRM macro. 


Note that RO is usually used by the $XABTRM-—STORE macro; thus, RO is 
not preserved and does not contain a return status. 
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modes ® 1—1 
run-time options ® 1—2 
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Access control list buffer field 
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See XAB$W_ACLSIZ field 
Access control list context field 
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Access control list error status field 
See XAB$L_ACLSTS field 
Access control list length field 
See XAB$W_ACLLEN field 
Access specification 
list of mask values ® 14-6 
ACE (access control list) 
VMS RMS limitation ¢ 14—2 
ACL (access control list) 
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avoiding use of ® 2-4 
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Allocation options field 
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3-8 
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using RO® 2-5 
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Backup date and time field 

See XAB$QO_BDT field 
BID field 

See Block identifier field 
BLN field 

See Block length field 
Block boundary option 

See FAB$V_BLK option 
Block code field 

See XAB$B_COD field 
Block |/O 

additional services that use * 4-23 

applicable services ® 4-23 

description * 4—23 

how to execute ®4—24 


how to specify for relative and indexed files © 
4-24 
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Block 1/O (cont’d.) 
program example ® 4—25 
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See XAB$B_BLN field 
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Block length field in protection XAB 
See XAB$B_BLN field 
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Block length field in terminal XAB 
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file organization considerations ® 5—4 
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Bucket size field 
See FAB$B_BKS field 
Bucket size field in allocation XAB 
See XAB$B_BKZ field 
Bucket size field in file header characteristics XAB 
See XAB$B_BKZ field 
Bucket split 
minimizing © 13—4 
BYTLM quota 
limiting size of user’s ACL buffer ® 14—3 


C 


Caller access mode ® 5—5 
Calling sequence ® 2—4 
Calling services ® 1-1 
Cancel CTRL/O option 
See RAB$V_CCO option 
Carriage return option 
See FAB$V_CR option 
CDT argument ® B—16 
Channel access mode protection option ® 5—5 
Channel access mode subfield 
See FAB$V_CHAN_MODE 
See FAB$V_CHAN_MODE subfield 
CHG (change) option 
in XAB$B_FLG field * B—2 1 
Close service 
condition values ®* RMS—5 
See also Completion status codes 
contrasted with Disconnect service ¢ 4—5 
control block input fields *RMS—4 
control block output fields * RMS—4 
function ® 4—1 
introduction @ 4—1 
limitations with XABs ® RMS—4 
use restrictions * RMS—4 
Collating key data type ® 13-6 
Collating sequence name field 
See XAB$L_COLNAM field 
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See XAB$L_COLSIZ field 
Collating sequence table field 
See XAB$L_COLTBL field 
Comment separator ® 3-6 
Completion routine 
condition for AST execution ® 3-11 
service macro arguments ® 3—11 





Completion status code 
description ® 2—5, A-9 to A-20 
errors for inaccessible control block condition 
2-6 
handling ¢ 3-12 
hexadecimal values *® A~2 to A—9 
listing conditions when not returned ® A—2 
severity codes ® 2-6 
testing *2—5 
Completion status code field 
use with debugger ® A-2 
Completion status code field in FAB 
See FAB$L_STS field 
Completion status code field in RAB 
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Completion status code value field 
use with debugger ® A—2 
Completion status field 
See also FAB$L_STS field 
as alternative to use of RO® 2—4 
for signaling errors ® 2-6 
Completion status value field 
as alternative to use of RO® 2-4 
for signaling errors ® 2-6 
Completion status value field in FAB 
See FAB$L_STV field 
Completion status value field in RAB 
See RAB$L_STV field 
Condition value 
See Completion status code 
Connect service © RMS—6 
comparing positioning for various file 
organizations ®° RMS—7 
condition values ®*RMS-—9 
connecting record stream ® 4—4 
control block input fields * RMS—7 
control block output fields * RMS-—8 
program example ® 4—12 
use with multiple keys © 4—12 
Contiguous best try option 
See FAB$V_CBT option 
Contiguous option 
See also FAB$V_CTG option 
See FAB$V_CTG option 
Continuation character ® 3—6 
Control block 
dual purpose ® 1—4 
field name conventions ¢ 2—2 
for extended attributes © 1—3 
for file name operations ® 1-3 
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for file services ® 1-2 
for record services ® 1—4 
macro names ® 3-2 
requirements for valid default values ® 1—4 
symbolic bit offset ¢ 2-4 
symbolic constant (keyword) value ¢ 2—4 
symbolic naming exceptions ® 2—3 
symbolic offsets © 2—2 
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Control block store macro 
description ® 3-1 
example ® 3-9 
placement guidelines ® 3—8 
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Control routine * 4—27 
CONVERT command ¢ 4-9 
Convert option 
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CREATE/FDL command ® 4-9 
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See also FAB$V_CIF option 
$CREATE macro ®3-10 
Create service ®RMS—10 
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contrasted with Open service ¢ 4—1 
control block input fields * RMS—1 1 
control block output fields * RMS—15 
function ® 4—1 
handling search list *RMS—1 1 
invoking ® 4—1 
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XAB override in various fields * RMS—1 1 
Creation date and time field 
See XAB$Q_CDT field 
CTRL/Z 
using as end-of-file marker ® RMS—49 
using to terminate Get service *RMS—49 
Current position option 
See FAB$V_POS option 
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DAP (data access protocol) ® 1—1 
Data access protocol 
See DAP 
Data bucket area number (DAN) 
program example ¢ 4—8 
Data bucket area number field 
See XAB$B_DAN field 
Data bucket fill size (DFL) 
program example ® 4-8 
Data bucket fill size field 
See XAB$W_DEFL field 
Data bucket size field 
See XAB$B_DBS field 
Data level 
comparing for primary and alternate keys ® 13-4 
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Date and time extended address block 
See XABDAT block 
Debugger 
use with completion status codes ® A—2 
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using ® 2—7 
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Default file extension quantity field in XABFHC 
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Default file specification string address field 
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See FAB$B_DNS field 
Default global buffer count field 
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Deferred write option 
See FAB$V_DFW option 
Delete on close option 
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Delete service * RMS—2 1 
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See also Completion status codes 
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program example ® 4—19 
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use restrictions © RMS-—2 1 
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Delete service option 
See FAB$V_DEL option 
Delete sharing option 
See FAB$V_SHRDEL option 
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using in control block arguments ® 3-5, 3-6, 
3-7 
$DEVDEF macro 
source of DEV field bit definitions * 5—7 
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See FAB$L_DEV field 
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See NAM$T_DVI field 
Device name address descriptor 
See NAM$L_DEV descriptor 
Device name address field 
See NAM$L_DEV field 
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See NAM$B_DEV field 
Device name size descriptor 
See NAM$B_DEV descriptor 
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See NAM$L_DIR descriptor 
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See NAM$W_DID 
Directory name length address field 
See NAM$L_DIR field 
Directory name length field 
See NAM$B_DIR field 
Directory size descriptor 
See NAM$B_DIR descriptor 
Disconnect service * RMS—23 
condition values ®° RMS—24 
See also Completion status codes 
control block input fields * RMS—24 
control block output fields * RMS—24 
program example ® 4—12 
using with multiple RABs © RMS-—24 
Disk cluster boundary 
determining allocation quantity * 5-3 
Display service *RMS—25 
condition values * RMS—28 
control block input fields *RMS—26 
control block output fields ¢ RMS—26 
requirements ® RMS—26 
DNA (default name address) argument ® B—5 
DNM (default name) argument ® B-3 
DNM (default name) field ¢ 4-3 


DNM (default name) keyword 
specifying FAB$L__DNA and FAB$B_DNS fields 
from VAX MACRO ® 5-9 
DNS (default name size) argument ® B—5 
DUP (duplicate) option 
in XAB$B_FLG field * B—2 1 
Duplicate key 
examples ® 7-8 
incompatibility between VMS RMS and RMS-—1 1 
° 13-9 
insertion order ®RMS—72 
retrieving records ® 7-8 
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EDT argument *® B—16 
End-of-file field in XABFHC 
See XAB$L_EBK field 
End-of-file mark 
positioning for user file open option ® 5-18 
End-of-file option 
See RAB$V_EOF option 
End-of-file positioning © RMS—7 
Enter service *RMS—29 
condition values ® RMS—31 
control block input fields * RMS—30 
control block output fields © RMS—30 
requirement for NAM block fields * RMS—30 
Erase service * RMS—32 
alternative © RVS—33 
condition values * RMS—34 
See also Completion status codes 
control block input fields * RMS—33 
control block output fields ° RMS—33 
requirements for using * RMS—33 
use restriction * RMS—33 
Error 
recommended method for signaling * 2-6 
Error completion routine * 2—5 
Error status code * 2—6 
from invalid control blocks * 2-6 
Escape sequence 
using from terminal devices * RMS—49 
ETO (extended terminal operation) option ® 
RMS—49 
Event flag 
for synchronous operations ® 2—7 
Executive-mode (PSL$C_EXEC) constant 
for FAB$V_CHAN_MODE ¢ 5—5 
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Expanded string 
requesting ® 6—2 

Expanded string area address (ESA) 
program example ® 4-12 

Expanded string area address field 
See NAM$L_ESA field 

Expanded string length field 
See NAM$B_ESL field 

Expanded string size field 
See NAM$B_ESS field 

Expiration date field 
See XAB$O_EDT field 

Extended attribute block 
See XAB block 

Extended attribute block address field 
See FABSL__XAB field 
See RAB$SL_XAB field 

Extended terminal operation option 
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Extend service * RMS—35 
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use restriction ® RMS—36 
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FAB$B_ACMODES 
See FAB$V_CHAN_MODE and FAB$V_LNM__ 
MODE 
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FAB$B_FAC field (cont’d.) 
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comparing with FAB$L_DEV field * 5-27 
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requirement for read-only buffer cache ® 5-20, 
5-28 
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use with other options * 5—28 
FAB$V_MXV option ® 5—15 
FAB$SV_NAM option ® 5—16 
FABSV_NEF option ® 5-17 
FAB$V_NFS option® 5-18 
relationship to CHAN_.MODE subfield ¢ 5—5 
FAB$V_NIL option * 5—28 
effect on specifying user file open option * 5—18 
precedence over other options ® 5—28 
requirement for block I/O * 4—23 
FAB$V_OFP option ® 5-16 
FAB$V_POS option ® 5-17 
subordinate to FAB$V_RWO option ® 5-17, 
5-18 
FAB$V_PRN option ® 5-24 
restriction against use with FAB$V_FTN and 
FAB$V_CR options® 5-23 
FAB$V_PUT option ® 5-11, 5-28 
use with block I/O operations ® 5—10 
FAB$V_RCK option ® 5—15 
restricted use ® 5-15 
FAB$V_RWC option ® 5-17 
FAB$V_RWO option® 5-17 
precedence over FAB$V_POS option ® 5-17, 
5-18 
FABS$V_SCF option ® 5-16 
qualified use by Close service * RMS—4 
use restriction ® 5-16 
FAB$V_SHRDEL option *® 5-28 
FAB$V_SHRGET option 
requirement for read-only buffer cache ® 5—20, 
5-28 
FAB$V_SPL option ® 5-16 
qualified use by Close service * RMS—4 
FAB$V_SQO option *® 5-14 
prohibiting random access * RMS—48 
FAB$V_SUP option ® 5—16 
subordinate to FAB$V_CIF option ® 5-15 
FABS$V_SYNCSTS option * 5—15 
FAB$V_TEF option® 5-14 
restriction to sequential files ®° 5-14 
FAB$V_TMD option ® 5-17 
inhibiting automatic Create *RMS-—29 
precedence over FAB$V_TMP option ® 5-17 
FAB$V_TMP option ® 5-17 
inhibiting automatic Create © RMS—29 
subordinate to FAB$V_TMD option ® 5—17 
FAB$V_TRN option 
in file access field ¢ 5—11 


requirement for truncate-on-put operation @ 
7-17 
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FAB$V_UFO option ® 5—18 
effect on internal structures © 5-20 
relationship to CHAN_MODE subfield ¢ 5—5 
FAB$V_UPD option® 5-11, 5-28 
requirement for implementing update-if option ® 
7-17 
requirement for Update service * 4—22 
FAB$V_UPI option ® 5-28 
reqirement for setting ®5—29 
requirement for block 1/0 * 4—23 
requirement for user file open option * 5-18 
FAB$V_WCK option ® 5-15 
restricted use ®5—15 
FABS$W_BLS field ® 5—5 
limitation * 5—5 
setting ®5—5 
FABSW_DEO field * 5-4, 5—6 
default logic * 5-6 
overriding default * 5—7 
FAB$W_.GBC field ® 5-19 
as output ® 5—19 
changing ® 5-19 
clearing ®5—19 
overriding default *5—19 
FAB$W_IFI field © 5-20 
FABSW_MRS field * 5-21 
as output ® 5-22 
program example ® 4—4 
summary ® 5—22 
use with fixed-length records ® 5-21 
use with variable-length records ® 5-21 
FAB (file access block) ® 5—1 
argument categories ® 1—2 
description ® 1-2 
requirements fore 5—2 
summary of fields ® 5—1 
$FAB macro ® B—2 
argument categories ¢ B—3 
$FAB_STORE macro ® B—4 
argument categories ® B—5 
FAB argument requirement ® B—5 
run-time arguments ¢ B—5 
FAC field 
See FAB$B_FAC field 
Fast delete option 
See RAB$V_FDL option 
FDLSPARSE ¢ 4-9 
FDLSRELEASE ¢ 4—9 
FDL Editor 
as alternative to multiple XABs in example ® 4—9 
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Field length 
identifier in symbolic name ® 2-3 
File 
characteristics argument for FAB® 1-2 
organizations ® 1-1 
specification argument for FAB® 1—2 
File access block 
See FAB 
File access block address field 
See RAB$L_FAB field 
File access field 
See FAB$B_FAC field 
File component descriptor 
address field * 6-3 
example ¢ 6—4 
field value logic * 6-3 
list of °6-3 
size field * 6-3 
suggested use of *6—4 
File Definition Language Editor 
See FDL Editor 
File extension 
using Extend service ® RUS—36 
File header characteristic extended address block 
See XABFHC 
See XABFHC block 
File identification field 
See NAM$W_FID field 
File name address descriptor 
See NAM$L_NAME descriptor 
File name address field 
See NAM$L_NAME field 
File name length field 
See NAM$B_NAME field 
File name size descriptor 
See NAM$B_NAME descriptor 
File name status field 
See NAM$L_FNB field 
File name string 
component parts ® 4-9 
File name string address( FAB$L__FNA) field 
how used to specify file name string ® 4—9 
File name string size (FAB$B_FNS) field 
how used to specify file name size * 4—9 
File organization and record format field 
See XAB$B_RFO field 
File organization field 
See FAB$B_ORG field 
File owner group number field 
See XAB$SW_GRP field 
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File owner group number field (cont’d.) 


in XABPRO field ® 14—4 
File owner member number field 
See XAB$W_MBM field 
File positioning 
effect on shared files © RMS—7 
File-processing 
services listed ® 3-3 
File-processing option 
as service output ® 5-12 
categories listed ® 5-12 
naming convention ® 5—12 
File-processing options field 
See FABSL__FOP field 
File protection extended address block 
See XABPRO block 
File protection field 
See XAB$W_PRO field 
File protection option field 
See XAB$B_PROT_OPT field 


File section 
defining in context of multiple volumes ® 
RMS-—56 
File sharing 


features ® 1—1 
File sharing field 
See FAB$B_SHR field 
File specification 
component descriptors ® 6~-2 
default requirements ® 4-9 
how handled by Search service * 4-9 
parsing ®* RUS—66 
File specification address 
See FAB$L_FNA field 
File specification size 
See FAB$B_FNS field 
File specification string address ® 4—9 
File specification string size ® 4—9 
File type address descriptor 
See NAM$L_TYPE descriptor 
File type address field 
See NAM$L_TYPE field 
File type length field 
See NAM$B_TYPE field 
File type size descriptor 
See NAM$B_TYPE descriptor 
File version address descriptor 
See NAM$L_VER descriptor 
File version address field 
See NAMS$L_VER field 


File version length field 
See NAM$B_VER field 
File version limit field 
See XAB$W_VERLIMIT field 
File version size descriptor 
See NAM$B_VER descriptor 
Fill level 
comparing primary key and alternate keys ® 
13-10 
Find service * RMS—38 
capabilities * RMS—39 
condition values ® RMS—4 1 
control block input fields * RMS—39 
control block output fields * RMS—41 
First data bucket start virtual block number field 
See XAB$L_DVB field 
First free byte field 
See XABSW_FFB field 
Fixed-length control area size field 
See FAB$B_FSZ field 
Fixed-length header control size field 
See XAB$B_HSZ field 
Fixed-length record format option 
See FAB$C_FIX option 
Flush service * RMS—43, RMS—44 
condition values * RMS—44 
See also Completion status codes 
control block input fields * RMS—44 
control block output fields © RMS-44 
FNA argument ® B—5 
FNM argument ® B-3 
FNM keyword 
for specifying FAB$L_FNA and FAB$B_FNS 
fields from VAX MACRO ® 5-11 
FNS argument ® B—5 
FORTRAN carriage control option 
See FAB$V_FTN option 
FORTRAN carriage control option list * 5-24 
Free service *RMS—45 
condition values * RMS—46 
control block input and output fields * RMS—46 


G 


$GET macro 

program example ® 4—16 
Get option 

See FAB$V_GET option 
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Get service * RMS—47, RMS-—53 
applicable access modes * RUS—48 
condition values ® RMS—53 
See also Completion status codes 
control block input fields © RMS-—50 
control block output fields *RMS-—53 
requirement for user record area ® RMS—50 
returning terminator character for terminal 
input ® RMS—49 
return status for various file access methods ® 
RMS—7 
using input from mailbox devices © RMS—50 
using stream input * RMS—48 
using terminal input *RMS—48 
using the RAB$L_STV field for additional status 
information® RMS—50 
Get sharing option 
See FAB$V_GET sharing option 
Global buffer ¢ 5—19 
determining number of *5—20 
Global buffer count field 
See FAB$W_GBC field 
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HDR1 labels 
accessing from XAB$B_MTACC field ® 14-5 
Highest virtual block field 


See XAB$L_HBK field 





1/O mode 
how to switch for sequential files * 4-24 
procedure for delaying decision until stream 
connection® 4—24 
when mode switching allowed ® 4—24 
Index bucket area number (JAN) 
program example ® 4—8 
Index bucket area number field 
See XAB$B_IAN field 
Index bucket fill size (IFL) 
program example ¢ 4—8 
Index bucket fill size field 
See XABSW_IFL field 
Index bucket size field 
See XAB$B_IBS field 
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Indexed file 


block allocation ¢ 8-3 

bucket size for multiple areas * RMS—15 
composition * RMS-—18 

creating ®RMS-18 

creating with multiple-key * 4—5 

default bucket size ° 5-3 

determinating key value * RMS—48 
determining keys and areas ® 17-1 
determining key size * 7-4 

determining maximum record size ® 5—2 1 
determining number of buffers © 7—6 
establishing index ® RMS—7 

example of processing duplicate keys * 7—8 
example of specifying ¢ 3—5 

fast delete option® 7-15 

identifying data area® 13-4 

inhibiting index update ® 13-12 

initial extent quantity * 5-3 

inserting records with Put service © RMS—7 1 
invoking Get and Find services for ® 7—4 
key of reference ® 7-3 

methods of accessing records ® 7~5 
options ® 7-10 

positioning area ® 8—7 

PROLOG selection * RMS-—19 

restriction against VFC format ® 5-18 
restriction to changing primary key ®*RMS—100 
separating index levels ® 13-1 1 

setting bucket size * 5-4 

size of data bucket ® 13-4 

specifying bucket size * 8—5 

specifying index area® 13-10 
specifying index bucket size® 13-10 
string key options ® 13-8 

update-if option ® 7-17 

use of areas in® 4-8 

use of end-of-file option *RMS-—7 
verifying sort order ® RMS-—7 

with allocation options ® 5-14 

with collating sequences® 13-3 

with deferred-write option ® RMS—12 
with Get service ®* RMS—48 

with XABKEY ¢ 13-1 


Index level 


comparing primary key and alternate keys ® 
13-10 


Initialization macro 


advantages described ® 3—7 
example ® 3—5 
functions ® 3—1 
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Initialization macro (cont'd.) 
multiple bit field ¢ 3—5 
placement guidelines ¢ 3—7 
using ® 3-6 

Inserting record 
program example * 4—16 

Internal file identifier field 
See FABSW_IFI field 

Internal stream identifier field 
See RABSW_ISI field 

lOSM._NOW modifier 
for Get and Put services ® 7—14 

Item list® 18-1 
guidelines for supplying ® 18-1 

Item list address field 
See XAB$L_ITEMLIST field 
See XAB$L_ITMLST field 

Item list extended address block 
See XABITM block 

Item list length field 
See XAB$W_ITMLST_LEN field 


J 


Journaling extended address block 
See XABJNL block 


K 


Key 
defining as simple or segmented ® 13-13 
determining match method ¢ 7—5 
example of finding and deleting a record® 4-20 
example of updating a record ® 4—21 
selecting path® 4-12 
size restriction for string type® 13-15 
types of matches ® 7-5 

Key buffer address field 
See RAB$L _KBF field 

Key definition extended address block 
See XABKEY block 

Key greater than 
See RAB$V_NXT option 

Key greater than or equal 
See RAB$V_EQNXT option 

Key name buffer address field 
See XAB$L_KNM field 








Key of reference 
establishing * RMS—48 
Key of reference field 
See RAB$B_KRPF field 
See XAB$_REF field 
Key option 
comparing primary and alternate keys® 13-8 
Key options flag field 
See XAB$B_FLG field 
Key position field 
See XAB$W_POSO through XAB$W_POS7 
field 
Key size field 
See RAB$B_KSZ field 
See XAB$B_SIZO through XAB$B_SIZ7 field 
Key string buffer 
program example ® 4—16 
Key string descriptor 
program example ® 4—16 
Key string length 
program example * 4—16 


L 


Length field 
using to indicate constant (keyword) value ¢ 2—4 
using to indicate mask or bit offset ® 2—3 
Level of root bucket field 
See XAB$B_LVL field 
LIBSGET_INPUT 
example of use in program ® 4—12 
LIBSPUT_OUTPUT 
example of use in program ® 4—12 
LIBSSIGNAL (or LIB$STOP) 
using to signal errors ® 2—6 
Limit option 
See RAB$V_LIM option 
Load option 
See RAB$V_LOA option 
Locate mode 
comparing with move mode for buffer handling ® 
7-15 
Locate mode option 
See RAB$V_LOC option 
Location field in XABALL 
See XAB$L_LOC field 
Lock record for read option 
See RAB$V_REA option 
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Lock record for write option 
See RAB$V_RLK 
Logical name translation 
requirements for parsing ® 4—9 
Logical name translation access mode subfield 
See FAB$V_LNM_MODE subfield 
Longest record length field 
See XABSW_LRL field 
Lowest level of index area number field 
See XAB$B_LAN field 


M 


Macro 
applicable VAX MACRO syntax rules © 3—5 
arguments for service completion routines ® 
3-11 
capabilities listed ¢ 4—1 
control block initialization © 3—1 
library location * 3—2 
names and control blocks ® 3-2 
naming conventions ® 3-2 
rules applicable to programming ® 3-6 
service ® 3—1 
using ® 3-6 
Macro field 
example of initializing ¢3—5 
setting at run time ® 3-5 
Magnetic tape accessibility field 
See XAB$B_MTACC field 
Manual unlock option 
See RAB$V_ULK option 
MAXBUF system parameter 
limiting size of user's ACL buffer ® 14-3 
Maximum record number field 
See FAB$L_MRN field 
Maximum record size 
default value for remote file access ® 5—22 
Maximum record size field 
See FABSW_MRS field 
Maximum record size field in XABFHC 
See XAB$W_MRZ field 
Maximum version option 
See FAB$V_MXvV option 
Minimum record length field 
See also XAB$W_MARL field 
in XABKEY # 13-12 
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Mixed !/O 
precautions listed * 4-24 
Mode field in XABITM 
See XAB$L_MODE field 
Mode switching 
when permitted ¢ 4—24 
Multiblock count field 
See RAB$B_MBC field 
Multibuffer count field 
See RAB$B_MBF field 
Multinational Character Set 
See DEC Multinational Character Set 
Multiple argument 
delimiting in control block fields®* 3—5, 3-7 
specifying in control block fields * B—3 
Multiple key 
example of use with Close service * 4—12 
performance cost of using ® 13-14 
recommended number ® 13-14 
Multiple-key indexed file 
creating ®° 4—5 
Multiple record stream 
with block 1/0 ®4—25 
Multistream access option 
See FAB$V_MSE option 


N 


NAM$B_BID field * 6—4 
NAM$B_BLN field ¢ 6—4 
NAM$B_DEV descriptor ¢ 6-3 
NAM$B_DEV field ¢ 6—4 
NAM$B_DIR descriptor ¢ 6-3 
NAM$B_DIR field ° 6—5 
NAM$B_ESL field ¢ 6-5 
NAMS$B_ESS field © 6—5 
NAM$B_NAME descriptor ® 6—3 
NAM$B_NAME field © 6—7 
NAM$B_NODE descriptor ¢ 6-3 
NAM$B_NODE field © 6—7 
NAM$B_NOP field ¢ 6—7 
options listed * 6-8 
NAM$B_RSL field © 6-9, RMS-63 
NAM$B_RSS field © 6-9 
NAM$B_TYPE descriptor * 6-3 
NAM$B_TYPE field * 6—9 
NAM$B_VER descriptor ® 6-3 
NAM$B_VER field © 6—10 
NAMS$L_DEV descriptor ¢ 6-3 
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NAMS$L_DEV field * 6-4 
NAMS$L _DIR descriptor ¢ 6-3 
NAM$L _DIR field * 6—5 
NAMS$L_ESA field © 6-5 
NAM$L _FNB field ® 6-6, RMS—63, RMS-—87 
NAMS$L __FNB status bit 

listing ¢ 6-6 
NAM$L_NAME descriptor ® 6-3 
NAMS$L_—NAME field © 6-7 
NAMS$L_NODE descriptor * 6-3 
NAMS$L_NODE field © 6—7 
NAMS$L_RLF field * 6—8 
NAMS$L_RSA field * 6-9, RMS-—63 
NAM$L_TYPE descriptor ¢ 6-3 
NAM$L_TYPE field © 6-9 
NAM$L_VER descriptor * 6-3 
NAMS$L _VER field * 6-10 
NAM$L_WCC field * 6-10 

returned by Remove service * RMS—82 
NAM$T_DVI field © 6-5 
NAM$V_CNCL_DEV bit © 6-6 
NAM$V_CONCEAL field ® RMS—26, RMS-63 
NAM$V_DIR_LVLS bit © 6-6 
NAM$V_EXP_DEV bit * 6-6 
NAM$V_EXP_DIR bit © 6-6 
NAM$V_EXP_NAME bit ® 6-6 
NAM$V_EXP_TYPE bit © 6—6 
NAM$V_EXP_VER bit © 6-6 
NAM$V_GRP_MBR bit © 6—6 
NAM$V_HIGHVER bit * 6-6 
NAM$V_LOWVER bit * 6-6 
NAM$V_NOCONCEAL option ® 6-8, RMS-—16, 

RMS-68 

NAMS$V_NODE bit ¢ 6-6 
NAMS$V_PPF bit © 6—6 
NAM$V_PWD field ® RMS—26, RMS-—63, RMS—68 
NAM$V_PWD option ® 6-8, RMS-16 
NAM$V_QUOTED bit * 6-6 
NAM$V_ROOT_DIR bit © 6—7 
NAM$V_SEARCH_LIST bit ¢ 6—7 
NAM$V_SRCHXABS option © 6-8 
NAM$V_SYNCHK option * 6—8, RMS-68 

use with Parse service ® 5—7 

using for Parse service without 1/O ®*RMS—67 
NAM$V_WILDCARD bit * 6—7 
NAM$V_WILD_GRP bit © 6-7 
NAM$V_WILD_MBR bit © 6—7 
NAM$V_WILD_NAME bit *° 6-7 
NAM$V_WILD_SFD1 bit *6—7 
NAM$V_WILD_TYPE bit ¢ 6—7 
NAM$V_WILD_UFD bit * 6-7 


NAM$V_WILD_VER bit ®© 6-7 
NAM$W__DID field © 6—4 
NAM$W_FID field ¢ 6-6 
NAM (name block) 
summary of fields ° 6-1 
using from higher-level language * 6—2 
using from VAX MACRO ® 6-2 
NAM (name block) option 


See FAB$V_NAM option 
Name block 
See NAM 
Name block address field 
See FAB$L_NAM field 
Name block options field 
See NAM$B_NOP field 
Naming convention 
macros ® 3-2 
services ® 3-3 
$NAM macro e B-6 
argument categories * B—6 
SNAM_STORE macro ¢ B—7 
argument categories ® B—7 
comparing with $NAM macro ¢ B—7 
NAMS$T_DVI argument ® B-7 
NAM$W_DID argument ® B—7 
NAM$W_FID argument ® B—7 
requirements ® B—7 
NBP (next block pointer) 
default for block transfer ® 7—2 
for block 1/0 ® 4-25 
functions listed ® 4-25 
NETWORK _BLOCK COUNT qualifier 
for specifying maximum record size ® 5—22 
Next block pointer 
See NBP 
Next key 
See RAB$V_NXT option 
Next or equal key option 
See RAB$V_EQNXT option 
Next Volume service *RMS—55 
condition values ® RMS—57 
control block input and output fields *RMS—56 
flush logic *RMS-—56 
input logic sequence * RMS—56 
output logic sequence * RMS—56 
requirements for using *RMS—56 
Node name address descriptor 
See NAM$L_NODE descriptor 
Node name address field 
See NAM$L_NODE field 
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Node name length field 

See NAM$B_NODE field 
Node name size descriptor 

See NAM$B_NODE descriptor 
No lock option 

See RAB$V_NLK option 
Nonexistent record option 

See RAB$V_NXR option 
Non-file-structured option 

See FAB$V_NFS option 
NOP field 

specifying multiple values * B—6 
No sharing option 

See FAB$V_NIL option 
Not end-of-file option 

See FAB$V_NEF option 
Null character field 

See XABSB_NUL field 
Number of allocation areas field 

See XAB$B_NOA field 
Number of key segments field 

See XAB$B_NSG field 
Number of keys field 

See XAB$B_NOK field 
Number sign (#) 

requirement for in control store macro ® 3-8 
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$OPEN macro 
expansion of ® 3-10 
for invoking the open service ¢ 4—1 
using in example ® 3-10, 3-11 
Open service ® RMUS—58 
condition values * RMS—64 
contrasted with Parse and Search services ® 
4-10 
control block input fields *RMS—59 
control block output fields © RMS—6 1 
function ¢ 4—1 
invoking ¢ 4—4 
NAM input fields © RMS—63 
NAM output fields © RMS—63 
program example ® 4—2 
requirements for using ®* RMS—59 
Option 
specifying by symbolic bit offset *2—3 
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Optional argument 


to service * 3-11 
Output file parse option 
See FAB$V_OFP option 
Output record buffer address field 
See RAB$L_RBF field 


P 


Packed decimal byte 
structure for key type ® 13-6 
Packed decimal string 
as key type ® 13-6 
$PARSE macro 
for processing wildcard characters ® 4—10 
Parse service ®°RMS-—66, RMS-—67 
condition values © RMS—69 
contro! block input fields * RMS—67 
control block output fields * RMS—68 
preparing for file search ® 4—9 
preparing for wildcard character processing ® 
RMS-67 
program example ¢ 4—9 
requirements for using ®RMS-—67 
Path to file 
file specification string address ® 4—9 
file specification string size * 4—9 
Performance 
improving with SHR argument ® 4—14 
Print format option 
See FAB$V_PRN option 
Print format options for VFC records with 2-byte 
control area® 5-25 
Program 
using wildcard characters ® 4—12 
Program execution mode 
using to call services ® 2—7 
Program interface ® 2—1 
Programming language 
using control blocks with ® 2-1 
Programming rules ® 3-6 
Prolog field 
See XAB$B_PROLOG field 
Prolog level ® RMS—18 
Prolog version number field 
See XAB$SW_PVN field 
Prompt buffer address field 
See RAB$L_PBF field 
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Prompt buffer size field 


See RAB$B_PSZ field 

Prompt option 
See RAB$V_PMT option 

Protection extended address block 
See XABPRO block 

Purge type-ahead option 
See RAB$V_PTA option 

$PUT macro 
program example ® 4—16 

Put service * RMS—70 
condition values ®* RMS—74 

See also Completion status codes 

control block input fields * RMS—73 
control block output fields © RMS—74 
inserting records by sort order *RMS-—72 
inserting records into indexed files * RMS—7 1 
inserting records into relative files ®*RMS—7 1 
inserting records into sequential files ®° RMS—7 1 
inserting records with duplicate keys *RMS—72 
record locking caution ®* RMS—72 
record-processing options ® 7—16 
requirements for using ®*RMS—72 
update-if logic ®¢ RMS—72 
using RAB$V_TPT option ® RMS-—7 1 
using RAB$V_UIF option ® RMS—7 1 
using with mailboxes ® RMS—7 1 
using with stream format files © RMS—7 1 

Put service option 
See FAB$V_PUT option 

Put sharing option 
See FAB$V_PUT sharing option 


R 


RO 
use by control block store macros ® 3-8 
use in asynchronous operations ® 2—5 
RAB (record access block) 
summary of fields ® 7-1 
RAB$B_BID field © 7-2 
RABS$B_BLN field * 7—3 
RABS$B_KRPF field * 7—4 
for selecting key path® 4-12 
for various services ¢ 7—4 
RAB$B_KSZ field * 7—4 
DECnet requirement ® 7—4 
key size compared to data types ® 7-4 
shared offset ® 7—4 





RAB$B_KSZ field (cont'd.) 
use with limit option ® 7-13 
use with search key® 7-12, 7-14 
RAB$B_MBC field * 7-5 
default logic ® 7-5 
performance benefit © 7-6 
use restriction® 7-5, 7-6 
RAB$B_MBF field © 7-6 
default logic *° 7-6 
performance benefit © 7—6 
use restriction ® 7-6 
use with read-ahead option® 7—16 
use with write-behind option ® 7-16 
values for various organizations ® 7-6 
RAB$B_PSZ field © 7—7 
shared offset ® 7—7 
RABSB_RAC field © 7—7 
options ® 7-7 
use restriction ® 7—7 
RAB$B_TMO field 
use with RAB$V_TMO option for mailbox 
service ® 7-14 
RAB$SB_TMO field ® 7-21 
for various record functions ® 7-21 
requirement for RAB$V_TMO option® 7-21 
use with timeout option for terminal operation 
7-19 
RAB$C_KEY option ® 7-8 
RAB$C_RFA option® 7-8 
RAB$C_SEO option ® 7-7 
RAB$L_BKT field 
as output ® 7-2 
use with block |/O® 7—2 
RAB$L_CTX field * 7-3 
RABS$L__FAB field * 7-3 
RABS$L_KBF field * 7-3 
shared offset ® 7-3 
use with limit option® 7—13 
use with RAB$B_KSZ field * 7—4 
use with search key® 7—12, 7-14 
RABS$L_PBF field ® 7-7 
requirement for carriage control ® 7—7 
RABS$L_RBF field*® 4—4, 7-8 
RAB$L_—RHB field * 7-9 
buffer size compatibility with FAB$B_FSZ ® 7-9 
default logic ® 7-9 
use by various services ® 7-9 
use restriction ® 7—9 
RAB$L_ROP field * 7—10 
options listed ® 7—10 
specifying key match method ® 7—5 
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RAB$L_STS field ¢ 7-20 
RABS$L_STVO field 
for returning terminating character © RMS—49 
RAB$L_STV field ® 7-20 
alternate access to ® 7—20 
for returning I/O status block *RMS—49 
for returning |/O status block from Put service ® 
RMS-74 
for returning PID from Put service ® RMS—7 1 
for returning process identification (PID) ¢ 
RMS-—50 
for returning record length ® RMS—53 
using with Get service *RMS-—50 
RABSL_UBF field * 7—21 
buffer logic * 7—2 1 
RAB$L_XAB field ® 7-22 
requirement for using XABTRM ® 18—1 
RAB$V_ASY option® 7-11, 7-14 
use restriction ® 7-15 
RAB$V_BIO option ® 7-11 
RAB$V_CCO options 7-18 
RAB$V_CVT option® 7-19 
RAB$V_EOF option ® 7—12 
RAB$V_EQNXT option® 7-12 
examples ® 7-13 
specifying key match method ® 7—5 
RAB$V_ETO option 
requirement for using XABTRM® 18—1 
RAB$V_FDL option ® 7—15 
use restriction ® 7-15 
RAB$V_KGE option 
See RAB$V_EQNXT option 
See RAB$V_NXT option 
RAB$V_LIM option ® 7—13 
RAB$V_LOA option® 7-13 
determining fill size 13—10 
example of use® 4-8 
use restriction® 13-4, 13-11 
RAB$V_LOC option® 7-15 
use restriction® 7-15 
RAB$V_NLK option ® 7-17 
precedence over RAB$V_ULK option ® 7-17 
RAB$V_NXR option ® 7—17 
output from Get service * 7—17 
relevant completion codes ® 7—17 
use restriction ® 7—17 
RAB$V_NXT option ® 7-14 
examples ® 7—14 
specifying key match method ® 7—5 
RAB$V_PMT option e 7—19 
RAB$V_PTA option® 7-19 
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RAB$V_RAH option® 7-12, 7-15 

default logic ® 7-16 

use restriction ® 7-16 
RAB$V_REA option® 7-17 

use restriction ® 7—17 
RAB$V_RLK option® 7-18 

precedence over RAB$V_REA option® 7—18 
RAB$V_RNE option® 7—19 
RABSV_RNF option ® 7-19 
RAB$V_RRL option ® 7-18 
RAB$V_SYNCSTS option * 7—16 
RAB$V_TMO option 

for immediate mailbox service ® 7-14 
RAB$V_TMO option® 7—14, 7-18, 7-19 
RAB$V_TPT option® 7-16 

use restriction ® 7-16 

using with Put service ®*RMS-—7 1 
RAB$V_UIF option ® 7-17 

effects on Put service ® 7-17 

use restriction for indexed files ® 7-17 

using with Put service *RMS—7 1 
RAB$V_ULK option® 7—18 

subordinate to RAB$V_NLK option® 7—18 
RAB$V_WAT option® 7-18, 7-19 

precedence over other options ® 7—19 

use with the RABSV_TMO option® 7-18 
RAB$V_WBH option® 7-12, 7-16 

default logic ® 7-16 

use restriction ® 7-16 
RAB$SW_ISI field © 7-3 
RAB$W_RFA field * 7—9 

additional symbolic offsets © 7-9 

as argument to $RAB_STORE macro ® B—12 

example ® 7-9 

guidelines for using ® 7-9 
RABSW_RSZ field ® 4—4, 7-20 

for various services ® 7—20 

operational notes listed ® 7—20 
RABSW_STVO offset 

alternate access to RAB$L_STV ® 7-20 
RABSW_STV2 field 

for returning length of escape sequence ® 

RMS-—49 

RABSW-_STV2 offset 

alternate access to RAB$L_STV ® 7-20 
RAB$W_USZ field * 7-21 

recommended value ® 7-2 1 

use with block I/O ® 7-22 
RAB$_V_WAT option 

use with timeout option for record locking ® 

7-18 
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RAB (record access block) 
arguments ®@ 1—4 
described in context of example ¢ 4—4 
description ® 1—4 
general description ® 7—1 
summary of fields ® 7—1 
$RAB macro *® B—9 
argument categories ® B—10 
$RAB_STORE macro ® B-11 
argument categories ® B—12 
comparing with $RAB macro ® B—11 
requirements ® B—12 
RFA argument ® B—12 
RDT (revision-date-time) argument ® B—16 
Read ahead option 
See RAB$V_RAH option 
Read check option 
See FAB$V_RCK option 
Read-no-echo option 
See RAB$V_RNE option 
Read no filter option 
See RAB$V_RNF option 
Read regardless of lock option 
See RAB$V_RRL option 
Read service * RMS—76 
condition values ®* RMS—78 
control block input fields * RMS—77 
control block output fields © RMS—77 
requirements for using ® RMS—77 
Record 
formats ® 1—1 
requirements for reading or writing in a file® 
4-12 
Record access block 
See RAB 
Record access field 
See RAB$B_RAC field 
Record attribute field 
See FAB$B_RAT field 
Record attributes field in XABFHC 
See XAB$B_ATR field 
Record buffer field 
See RAB$L_RBF field 
Record file address field 
See RAB$W_FFA field 
Record format field 
See FAB$B_RFM field 
Record header buffer field 
See RAB$L_RHB field 
Record |/O 
how to execute ® 4-24 


Record locking record-processing options ® 7—17 
Record-processing 
services listed ® 3-3 
Record-processing macro 
format example ® 3-12 
Record-processing option 
for Connect service ® 7—10 
Record-processing options field 
See RAB$L_ROP field 
Record size field 
See RAB$W_RSZ field 
Record stream 
in the context of a RAB® 7—1 
Recovery unit extended address block 
See XABRU block 
Recovery unit XAB 
See XABRU block 
Register. 
saving when making call ® 2—4 
Register O 
See RO 
Related file identification field 
See XABSW_ARFI field 
Related file identification field in XABALL 
See XAB$W_FFI field 
Related file NAM block address field 
See NAM$L_RLF field 
Relative file 
buffer requirement ® 7—6 
defining cell size * 5-21 
description of relative record number ® 7—5 
determining record lengthe 5-21 
establishing highest record number ® 5—2 1 
nonexistent record processing ® 7—17 
omitting initial prezeroing * 4-23 
random access ® 7-3 
record size limit ® 5-21 
RFA value * 7-9 
specifying bucket size * 8—5 
specifying cell sizee 10—5 
Relative file field 
record access ® 7—2 
Relative volume number field 
See XABSW_VOL field 
Release service * RUS—79, RMS—80 
condition values * RMS—80 
control block input and output fields * RMS—80 
Remove service ®* RMS—81, RMS-—82 
caution against mixing with Search service ® 
RMS-—82 
comparing with Erase service * RMS—82 
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condition values * RMS—84 
control block input fields * RMS—82 
control block output fields *RMS-—83 
improving performance ® RMS-—82 
requirements for using * RMS—82 
use with wildcard characters and search lists ® 
RMS-82 
Rename service *RMS-—85, RMS-—86 
alternative to specifying arguments to 
$RENAME macroe RMS—86 
condition values * RMS—-88 
control block input fields *RMS—86 
control block output fields * RMS—87 
exception in argument list ®2—5 
format ® 3-11 
indicating successful completion ® 4—16 
program example ® 4—14 
requirements for using ° RMS—86 
Reserved event flag 
use of °2—7 
Restriction 
to calling services © 2—7 
Resultant string 
requesting © 6—2 
Resultant string area address field 
See NAM$L_RSA field 
Resultant string area size field 
See NAM$B_RSS field 
Resultant string length field 
See NAM$B_RSL field 
Retrieval window size field 
See FAB$B_RTV field 
Retrieving record 
program example ® 4—16 
Revision date and time extended address block 
See XABRDT block 
Revision date and time field 
See XAB$Q_RDT field 
Revision number field 
See XABSW_RVN field 
Rewind on close option 
See FAB$V_RWC option 
Rewind on open option 
See FAB$V_RWO option 
Rewind service *RMS~—89, RMS—90 
condition values * RMS—90 
control block input fields * RMS~—90 
control block output fields © RMS—90 
use restriction ® RMS—90 
RMS$_OK_LIM success status code ® 7—13 
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RMS-—11 
block identifier field limitation * 5—3 
$RMSDEF macro 
access to symbolic offset names ® 2—2 
RMS_DFNBC system parameter 
for specifying default network block count ® 
5-22 
Root index bucket virtual block field 
See XAB$L_RVB field 
Run-time 
access options ® 1-2 
implementation of services ® 4—1 
information ® 1—4 
processing environment® 2-1 
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Search 
synonyms ® 7—12 
Search list 
as alternative to using wildcard characters ® 
4-10 
using with Remove service ® RMS—82 
$SEARCH macro 
for processing wildcard characters ® 4—10 
Search service * RMS—91, RMS—92 
condition values ®* RMS—94 
control block input fields *RMS—92 
control block output fields * RMS—93 
example of completion code handling ® 4-12 
program example ® 4—9 
requirement for Parse service ® 4-9 
using with wildcard characters and search lists ® 
RMS-92 
Search string translation 
requirements for parsing ® 4—9 
Secondary device characteristics field 
See FAB$L_SDC field 
Segmented key ® 13-13 
restriction against overlapping ® 13—13 
Separator 
in symbolic name ® 2-3 
Sequential only option 
See FAB$V_SQO option 
Service 
allowable program execution modes ® 2—7 
block 1/0 3-5 
calling example ® 3—1 4 
invoking at run time ® 3-1 
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naming conventions ® 3—3 
passing argument list to® 3-10 
Service macro 
description ¢ 3-1 
for creating and processing files ® 4—1 
format ® 3-10, 3-11 
format rules ® 3-11 
types ® 3-12 
Services 
restrictions to calling * 2—7 
SET FILE command 
for changing global buffer count value * 5—19 
SET RMS_DEFAULT command ® 7-6 
to limit default extension quantity ® 5-6 
Set system failure exception mode 
See SYS$SETSFM 
Severity code 
in completion status code field * 2-6 
S field in symbolic offset 
for specifying field length * 2-3 
Shared access 
requirement to specify ® 4—1 
Shared file 
end-of-file positioning * RMS—7 
SHR field 
See FAB$SB_SHR field 
Sign representation 
preference for key type coding ® 13-7 
Simple key ® 13-13 
Sort order 
establishing ® 7-5 
Space service *RMS—95 
condition values ®* RMS—96 
control block input fields * RMS—96 
control block output fields * RMS—96 
Spool file option 
See FAB$V_SPL option 
Starting logical block number field 
See XAB$L_SBN field 
Stream record format option 
See FAB$C_STM option 
Stream record format with carriage return option 
See FAB$C_STMCR option 
Stream record format with line feed option 
See FAB$C_STMLF option 
STS (status) field 


See also Completion status field 


See also FAB$L_STV field 
contents ® 2—6 


STV (status value) field 


See also Completion status value field 

contents ¢ 2-6 
Submit command file option 

See FAB$V_SCF option 
Success completion routine * 2—5 
Summary extended address block 

See XABSUM block 
Summary XAB 

for key information ® 13-1 
Supersede existing file option 

See FAB$V_SUP option 
Supervisor-mode (PSL$C_SUPER) constant 

for FAB$V_CHAN_MODE ¢ 5-5 
Symbol definition macro 

description ® 3—1 

using ® 3-7 
Symbolic address 

use in locating start of control block * 3—7 
Symbolic bit offset 

use in specifying options ® 2-3 
Symbolic naming exception 

control block ¢ 2—3 
Symbolic offset 

control block ¢ 2—4 

format ¢ 2—2 

use in locating control block fields ® 2—2 
Synchronous status option 

See FAB$V_SYNCSTS option 

See RAB$V_SYNCSTS option 
SYS$BINTIM ® 3—10 
SYS$CLOSE 

See Close service 
SYS$CONNECT 

See Connect service 
SYS$CREATE 

See Create service 
SYS$DELETE 

See Delete service 
SYS$DISCONNECT 

See Disconnect service 
SYS$DISPLAY 

See Display service 
SYSSENTER 

See Enter service 
SYSS$ERASE 

See Erase service 
SYS$SEXTEND 

See Extend service 
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SYS$FIND 

See Find service 
SYS$FLUSH 

See Flush service 
SYS$FREE 

See Free service 
SYS$GET 

See Get service 
SYS$LIBRARY:STARLET.MLB 

as source of macros ® 1—1 
SYSSNXTVOL 

See Next Volume service 
SYS$OPEN 

See Open service 
SYS$PARSE 

See Parse service 
SYS$PUT 

See Put service 
SYS$QIO 

for additional processing ® 5-18 

use in !/O operation ® 2—7 
SYS$READ 

See Read service 
SYS$RELEASE 

See Release service 
SYS$REMOVE 

See Remove service 
SYSSRENAME 

See Rename service 

noting format difference ® 3-11 
SYS$REWIND 

See Rewind service 
SYSSSEARCH 

See Search service 
SYS$SSETSFM 

use in signaling errors ®2—6 
SYS$SPACE 

See Space service 
SYS$STRUNCATE 

See Truncate service 
SYSSUPDATE 

See Update service 
SYSSWAIT 

See Wait service 
SYSSWRITE 

See Write service 
SYSPRV privilege 

requirement for creating files with different UIC « 

14-8 
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System service exception * 2-6 
System service exception generation 
disabling * 2-6 


7 


Temporary file delete option 
See FAB$V_TMD option 
Temporary file option 
See FAB$V_TMP option 
Terminal device record-processing option ® 7-18 
Terminal extended address block 
See XABTRM block 
Terminal read operation 
RAB$L_ROP field options *® 18-2 
T field in symbolic offset 
for specifying varying field length*® 2—3 
Timeout field 
See RABSB_TMO field 
Timeout option 
See RAB$V_TMO option 
Total key size field 
See XAB$B_TKS field 
Truncate at end-of-file option 
See FAB$V_TEF option 
Truncate-on-put option 
See RAB$V_TPT option 
Truncate option 
See FAB$V_TRN option 
Truncate service * RMS—97 
condition values © RMS—98 
See also Completion status codes 
control block input fields © RMS—98 
control block output fields ¢ RMS—98 
use restriction ®* RMS—97 
Type code field in allocation XAB 
See XAB$B_COD field 
Type code field in date and time XAB 
See XAB$B_COD field 
Type code field in file header characteristics XAB 
See XAB$B_COD field 
Type code field in item list XAB 
See XAB$B_COD field 
Type code field in key XAB 
See XAB$B_COD field 
Type code field in protection XAB 
See XAB$B_COD field 
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Type code field in revision date and time XAB 
See XAB$B_COD field 

Type code field in summary XAB 
See XAB$B_COD field 

Type code field in terminal XAB 
See XAB$B_COD field 
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UIC (user identification code) 
delimiting in control block fields * 3—7 
Undefined record format option 
See FAB$C_UDF option 
Update-if option 
See RAB$V_UIF option 
Update service ®* RMS—99, RMS—100 
comparing with Put service for stream format 
files ¢ RMS—100 
condition values ®RMS-—101 
control block input fields © RMS—100 
control block output fields *RMS—101 
invoking ® 5-11 
program example ® 4—20 
requirements for using * RMS—100 
using with indexed files © RMS—100 
Update sharing option 
See FAB$V_UPD option 
User context field 
See RAB$L_CTX field 
User-entered reply 
as used in example for selecting key pathe 4-12 
User file-open option 
See FAB$V_UFO option 
User identification code field 
See XAB$L_UIC field 
User-mode (PSL$C_USER) constant 
for FAB$V_CHAN_MODE ¢ 5-5 
User process interlock option 
See FAB$V_UPI option 
User prompt string 
program example ¢ 4—16 
User record buffer address field 
See RAB$SL_UBF field 
User record buffer size field 
See RAB$W_USZ field 
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Variable-length format option 

See FAB$C_VAR option 
Variable-length record 

guidelines for specifying ® 5-21 
VAX language 

use with control blocks ® 2—1 
VAX MACRO 

See Macro 
VAX Procedure and Condition Handling Standard 

for calling services * 3-3 
VFC record format option 

See FAB$C_VFC option 
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$WAIT macro 
format difference * 3-12 
Wait option 
See RAB$V_WAT option 
Wait service *RMS-102 
condition values * RMS-—103 
control block input and output fields * RMS—102 
Wildcard character 
use with Remove service ®* RMS-—82 
use with Search service ¢ 4—10 
Wildcard context field 
See NAM$L_WCC field 
Wildcard substitution 
specifying NAM$L_RSA field * 6-9 
Write-behind option 
See RAB$V_WEBH option 
Write check option 
See FAB$V_WCK option 
Write service *RMS—104, RMS-—105 
condition values ®* RMS—106 
control block input fields *RMS-—105 
control block output fields * RMS—105 
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XAB$B_AID field * 8-2 
XABS$B_ALN field © 8-2 
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XAB$B_AOP field * 8-3 
options ® 8—4 
XAB$B_ATR field ® 10-2 
options ® 10-2 
XAB$B_BKZ field 
as output * 8-5 
default logic * 8-5 
determining bucket size ® 8—5 
in allocation XAB (XABALL) ® 8-4 
in file header characteristics allocation XAB 
(XABFHC)® 10-3 
RMS-—11 restriction ®¢8—5 
size requirements for multiple index areas ® 8—5 
XAB$B_BLN field 
in allocation XAB (XABALL) ® 8—5 
in date and time XAB (XKABDAT) ¢ 9-2 
in file header characteristics XAB (XKABALL) ® 
10-3 
in item list XAB (XABITM) ¢ 11-2 
in key XAB (XABKEY) ¢ 13—2 
in protection XAB (XABPRO) ® 14—4 
in revision date and time XAB (XABRDT)e 15—2 
in summary XAB (KABSUM) ¢ 17-1 
in terminal XAB (KABTRM) ¢ 18-2 
XAB$B_COD field 
See also COD field 
in allocation XAB (XABALL) ¢ 8-5 
in date and time XAB (KABDAT) ¢ 9-3 
in file header characteristics XAB (XABFHC) ¢ 
10-3 
in item list XAB (XABITM) ¢ 11-2 
in key XAB (XABKEY) ¢ 13-2 
in protection XAB (KABPRO) ® 14-4 
in revision date and time XAB (XABRDT) ® 15-2 
in summary XAB (KABSUM) ¢ 17-1 
in terminal XAB (XKABTRM) ® 18~2 
XAB$B_DAN field © 13—4 
requirement for ® 13—4 
XAB$B_DBS field * 13—4 
XAB$B_DTP field ® 13-5 
data formats ® 13-6 
data type restrictions ® 13-5 
options © 13—5 
use with search key ® 7-13, 7-14 
value prefixes for sorting ® 13-5 
XAB$B_FLG field * 13-8, B-21 
option allowable combinations listed ® 13—9 
options ® 13-8 
XAB$B_HSZ field ® 10-4 
use restriction ® 10—4 


Index—21 


Index 


XABS$B_IAN field * 13-10 
conditional usage ® 13-10 
indicating index level * 8—5 

XAB$B_IBS field ® 13-10 

XAB$B_LAN field ® 13-11 
indicating index level ® 8—5 
relationship to XAB$B_AID field * 13-11 
requirement for compatibility with XAB$B_IAN 

field® 13-11 
use restriction ® 13-11 

XAB$B_LVL field ® 13-12 

XAB$B_MTACC field ® 14-5 
default logic ® 14—5 
valid character codes ® 14-5 

XAB$B_NOA field ® 17-2 

XABS$B_NOK field ® 17-2 

XAB$B_NSG field ® 13-12 

XAB$B_NUL field ® 13-12 
use restrictions ® 13-12 

XAB$B_PROLOG field ® 13-13 
default logic ® 13-13 
service usage ® 13-13 
use restriction ® 13-13 

XAB$B_PROT_OPT field * 14—7 

XAB$B_RFO field ® 10-5 
values listed ® 10—6 

XAB$B_SIZO through XAB$B__SIZ7 field® 13-14 
default logic ® 13-15 
requirement for compatibility with XAB$W_. 

POSO through XAB$W_POS7 field ® 13-14 
with segmented key ® 13-14 
with simple key ® 13-14 

XAB$B_TKS field ® 13-15 

XAB$C_ALLEN value ® 8—5 

XAB$C_ALL value * 8-6 

XAB$C_DATLEN value ® 9—2 

XAB$C_DAT value * 9-3 

XAB$C_FHCLEN value ® 10-3 

XAB$C_FHC value ® 10-3 

XAB$C_ITMLEN value ® 11-2 

XAB$C_ITM value ® 11-2 

XAB$C_KEYLEN value ® 13-2 

XAB$C_KEY value ® 13-2 

XAB$C_PROLEN value ® 14-4 

XAB$C_PRO value ® 14—4 

XAB$C_RDTLEN value ® 15-2 

XAB$C_RDT value * 15-2 

XAB$C_SUMLEN value ® 17-1 

XAB$C_SUM value ® 17-2 

XAB$C_TRMLEN value ® 18-2 

XAB$C_TRM value ® 18-2 
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XAB$L_ACLBUF field * 14-2 
determining value for Create service * 14-2 
determining value for Open and Display service ® 
14-2 
handling ACE ® 14—2 
XAB$L_ACLCTX field® 14-2, 14-3 
XAB$L_ACLSTS field ® 14-3 
error handling guidelines ¢ 14—3 
use restriction ® 14—4 
XAB$L_ALO ® 8-3 
XAB$L_COLNAM field ® 13-2 
XAB$L_COLSIZ field * 13-3 
XAB$L_COLTBL field * 13-3 
XAB$L_DVB field ® 13-7 
XABS$L __EBK field ® 10-3 
XABS$L_HBK field © 10-4 
comparing with FAB$L_ALO field * 10-4 
XAB$L_ITEMLIST field® 11-2 
XAB$L_ITMLST field © 18-2 
requirement for valid terminal driver ® 18—1 
XAB$L_KNM field © 13-11 
XAB$L_LOC field * 8—6 
determining value * 8-6 
requirement for alignment option * 8-6 
XAB$L_MODE field ® 11-2 
XAB$L_NXT field 
in XABALL ¢ 8-6 
in XABDAT ¢ 9-3 
in XABFHC e 10-5 
in XABKEY ¢ 13-12 
in XABPRO @ 14—5 
in XABRDT ¢ 15—2 
in XABSUM ¢ 17-2 
in XABTRM® 18-3 
XABS$L_RVB field ® 13-14 
XAB$L_SBN field® 10-6 
XAB$L_UIC field® 14—4, 14-8 
combining the XAB$W_GRP and XABSW_ 
MBM fields © 14—8 
order of determining value ® 14—8 
setting XAB$W_GRP field * 14-4 
setting XAB$W_MBM field® 14—5 
XAB$NXT field 
in XABITM®e 11—2 
XAB$Q_BDT field * 9-2 
XAB$Q_CDT field * 9-2 
XAB$Q_EDT field * 9-3 
XAB$Q_RDT field® 9-3, 15—2 
XAB$V_BLK option® 10-2 
XAB$V_CBT option ® 8—4 


XAB$V_CHG option® 13-8 

use restriction ® 13-8 
XAB$V_CR option ® 10-2 
XAB$V_CTG option ® 8-4 
XAB$V_DAT_NCMPR option * 13-8 
XABS$V_DUP option® 13-8 
XABS$V_FTN option® 10-2 
XABS$V_HRD option ¢ 8—4 

use restrictions ® 8-4 
XAB$V_IDX_NCMPR option ® 13-8 
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